@browserbasehq/orca 3.0.1 → 3.0.2

package/dist/index.js

@@ -81,6 +81,278 @@ var __async = (__this, __arguments, generator) => {
   });
 };
 
+// lib/version.ts
+var STAGEHAND_VERSION;
+var init_version = __esm({
+  "lib/version.ts"() {
+    STAGEHAND_VERSION = "3.0.2";
+  }
+});
+
+// lib/v3/types/public/sdkErrors.ts
+var StagehandError, StagehandDefaultError, StagehandEnvironmentError, MissingEnvironmentVariableError, UnsupportedModelError, UnsupportedModelProviderError, UnsupportedAISDKModelProviderError, InvalidAISDKModelFormatError, StagehandNotInitializedError, BrowserbaseSessionNotFoundError, CaptchaTimeoutError, MissingLLMConfigurationError, HandlerNotInitializedError, StagehandInvalidArgumentError, StagehandElementNotFoundError, AgentScreenshotProviderError, StagehandMissingArgumentError, CreateChatCompletionResponseError, StagehandEvalError, StagehandDomProcessError, StagehandClickError, LLMResponseError, StagehandIframeError, ContentFrameNotFoundError, XPathResolutionError, ExperimentalApiConflictError, ExperimentalNotConfiguredError, CuaModelRequiredError, ZodSchemaValidationError, StagehandInitError, MCPConnectionError, StagehandShadowRootMissingError, StagehandShadowSegmentEmptyError, StagehandShadowSegmentNotFoundError, ElementNotVisibleError, ResponseBodyError, ResponseParseError, TimeoutError, PageNotFoundError, ConnectionTimeoutError;
+var init_sdkErrors = __esm({
+  "lib/v3/types/public/sdkErrors.ts"() {
+    init_version();
+    StagehandError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+      }
+    };
+    StagehandDefaultError = class extends StagehandError {
+      constructor(error) {
+        if (error instanceof Error || error instanceof StagehandError) {
+          super(
+            `
+Hey! We're sorry you ran into an error. 
+Stagehand version: ${STAGEHAND_VERSION} 
+If you need help, please open a Github issue or reach out to us on Slack: https://stagehand.dev/slack
+
+Full error:
+${error.message}`
+          );
+        }
+      }
+    };
+    StagehandEnvironmentError = class extends StagehandError {
+      constructor(currentEnvironment, requiredEnvironment, feature) {
+        super(
+          `You seem to be setting the current environment to ${currentEnvironment}.Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`
+        );
+      }
+    };
+    MissingEnvironmentVariableError = class extends StagehandError {
+      constructor(missingEnvironmentVariable, feature) {
+        super(
+          `${missingEnvironmentVariable} is required to use ${feature}.Please set ${missingEnvironmentVariable} in your environment.`
+        );
+      }
+    };
+    UnsupportedModelError = class extends StagehandError {
+      constructor(supportedModels, feature) {
+        super(
+          feature ? `${feature} requires one of the following models: ${supportedModels}` : `please use one of the supported models: ${supportedModels}`
+        );
+      }
+    };
+    UnsupportedModelProviderError = class extends StagehandError {
+      constructor(supportedProviders, feature) {
+        super(
+          feature ? `${feature} requires one of the following model providers: ${supportedProviders}` : `please use one of the supported model providers: ${supportedProviders}`
+        );
+      }
+    };
+    UnsupportedAISDKModelProviderError = class extends StagehandError {
+      constructor(provider, supportedProviders) {
+        super(
+          `${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`
+        );
+      }
+    };
+    InvalidAISDKModelFormatError = class extends StagehandError {
+      constructor(modelName) {
+        super(
+          `${modelName} does not follow correct format for specifying aiSDK models. Please define your model as 'provider/model-name'. For example: \`model: 'openai/gpt-4o-mini'\``
+        );
+      }
+    };
+    StagehandNotInitializedError = class extends StagehandError {
+      constructor(prop) {
+        super(
+          `You seem to be calling \`${prop}\` on a page in an uninitialized \`Stagehand\` object. Ensure you are running \`await stagehand.init()\` on the Stagehand object before referencing the \`page\` object.`
+        );
+      }
+    };
+    BrowserbaseSessionNotFoundError = class extends StagehandError {
+      constructor() {
+        super("No Browserbase session ID found");
+      }
+    };
+    CaptchaTimeoutError = class extends StagehandError {
+      constructor() {
+        super("Captcha timeout");
+      }
+    };
+    MissingLLMConfigurationError = class extends StagehandError {
+      constructor() {
+        super(
+          "No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client is required to use act, extract, or observe."
+        );
+      }
+    };
+    HandlerNotInitializedError = class extends StagehandError {
+      constructor(handlerType) {
+        super(`${handlerType} handler not initialized`);
+      }
+    };
+    StagehandInvalidArgumentError = class extends StagehandError {
+      constructor(message) {
+        super(`InvalidArgumentError: ${message}`);
+      }
+    };
+    StagehandElementNotFoundError = class extends StagehandError {
+      constructor(xpaths) {
+        super(`Could not find an element for the given xPath(s): ${xpaths}`);
+      }
+    };
+    AgentScreenshotProviderError = class extends StagehandError {
+      constructor(message) {
+        super(`ScreenshotProviderError: ${message}`);
+      }
+    };
+    StagehandMissingArgumentError = class extends StagehandError {
+      constructor(message) {
+        super(`MissingArgumentError: ${message}`);
+      }
+    };
+    CreateChatCompletionResponseError = class extends StagehandError {
+      constructor(message) {
+        super(`CreateChatCompletionResponseError: ${message}`);
+      }
+    };
+    StagehandEvalError = class extends StagehandError {
+      constructor(message) {
+        super(`StagehandEvalError: ${message}`);
+      }
+    };
+    StagehandDomProcessError = class extends StagehandError {
+      constructor(message) {
+        super(`Error Processing Dom: ${message}`);
+      }
+    };
+    StagehandClickError = class extends StagehandError {
+      constructor(message, selector) {
+        super(
+          `Error Clicking Element with selector: ${selector} Reason: ${message}`
+        );
+      }
+    };
+    LLMResponseError = class extends StagehandError {
+      constructor(primitive, message) {
+        super(`${primitive} LLM response error: ${message}`);
+      }
+    };
+    StagehandIframeError = class extends StagehandError {
+      constructor(frameUrl, message) {
+        super(
+          `Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`
+        );
+      }
+    };
+    ContentFrameNotFoundError = class extends StagehandError {
+      constructor(selector) {
+        super(`Unable to obtain a content frame for selector: ${selector}`);
+      }
+    };
+    XPathResolutionError = class extends StagehandError {
+      constructor(xpath) {
+        super(`XPath "${xpath}" does not resolve in the current page or frames`);
+      }
+    };
+    ExperimentalApiConflictError = class extends StagehandError {
+      constructor() {
+        super(
+          "`experimental` mode cannot be used together with the Stagehand API. To use experimental features, set experimental: true, and useApi: false in the stagehand constructor. To use the Stagehand API, set experimental: false and useApi: true in the stagehand constructor. "
+        );
+      }
+    };
+    ExperimentalNotConfiguredError = class extends StagehandError {
+      constructor(featureName) {
+        super(`Feature "${featureName}" is an experimental feature, and cannot be configured when useAPI: true. 
+    Please set experimental: true and useAPI: false in the stagehand constructor to use this feature. 
+    If you wish to use the Stagehand API, please ensure ${featureName} is not defined in your function call, 
+    and set experimental: false, useAPI: true in the Stagehand constructor. `);
+      }
+    };
+    CuaModelRequiredError = class extends StagehandError {
+      constructor(availableModels) {
+        super(
+          `To use the computer use agent (CUA), please provide a CUA model in the agent constructor or stagehand config. Try one of our supported CUA models: ${availableModels.join(", ")}`
+        );
+      }
+    };
+    ZodSchemaValidationError = class extends Error {
+      constructor(received, issues) {
+        super(`Zod schema validation failed
+
+\u2014 Received \u2014
+${JSON.stringify(received, null, 2)}
+
+\u2014 Issues \u2014
+${JSON.stringify(issues, null, 2)}`);
+        this.received = received;
+        this.issues = issues;
+        this.name = "ZodSchemaValidationError";
+      }
+    };
+    StagehandInitError = class extends StagehandError {
+      constructor(message) {
+        super(message);
+      }
+    };
+    MCPConnectionError = class extends StagehandError {
+      constructor(serverUrl, originalError) {
+        const errorMessage = originalError instanceof Error ? originalError.message : String(originalError);
+        super(
+          `Failed to connect to MCP server at "${serverUrl}". ${errorMessage}. Please verify the server URL is correct and the server is running.`
+        );
+        this.serverUrl = serverUrl;
+        this.originalError = originalError;
+      }
+    };
+    StagehandShadowRootMissingError = class extends StagehandError {
+      constructor(detail) {
+        super(
+          `No shadow root present on the resolved host` + (detail ? `: ${detail}` : "")
+        );
+      }
+    };
+    StagehandShadowSegmentEmptyError = class extends StagehandError {
+      constructor() {
+        super(`Empty selector segment after shadow-DOM hop ("//")`);
+      }
+    };
+    StagehandShadowSegmentNotFoundError = class extends StagehandError {
+      constructor(segment, hint) {
+        super(
+          `Shadow segment '${segment}' matched no element inside shadow root` + (hint ? ` ${hint}` : "")
+        );
+      }
+    };
+    ElementNotVisibleError = class extends StagehandError {
+      constructor(selector) {
+        super(`Element not visible (no box model): ${selector}`);
+      }
+    };
+    ResponseBodyError = class extends StagehandError {
+      constructor(message) {
+        super(`Failed to retrieve response body: ${message}`);
+      }
+    };
+    ResponseParseError = class extends StagehandError {
+      constructor(message) {
+        super(`Failed to parse response: ${message}`);
+      }
+    };
+    TimeoutError = class extends StagehandError {
+      constructor(operation, timeoutMs) {
+        super(`${operation} timed out after ${timeoutMs}ms`);
+      }
+    };
+    PageNotFoundError = class extends StagehandError {
+      constructor(identifier) {
+        super(`No Page found for ${identifier}`);
+      }
+    };
+    ConnectionTimeoutError = class extends StagehandError {
+      constructor(message) {
+        super(`Connection timeout: ${message}`);
+      }
+    };
+  }
+});
+
 // lib/v3/logger.ts
 function bindInstanceLogger(instanceId, logger) {
   instanceLoggers.set(instanceId, logger);
@@ -951,7 +1223,11 @@ function resolveFocusFrameAndTail(page, absoluteXPath, parentByFrame, rootId) {
         selectorForIframe,
         ctxFrameId
       );
-      if (!objectId) throw new Error("Failed to resolve iframe element by XPath");
+      if (!objectId)
+        throw new StagehandIframeError(
+          selectorForIframe,
+          "Failed to resolve iframe element by XPath"
+        );
       try {
         yield parentSess.send("DOM.enable").catch(() => {
         });
@@ -972,7 +1248,10 @@ function resolveFocusFrameAndTail(page, absoluteXPath, parentByFrame, rootId) {
           }
         }
         if (!childFrameId)
-          throw new Error("Could not map iframe to child frameId");
+          throw new StagehandIframeError(
+            selectorForIframe,
+            "Could not map iframe to child frameId"
+          );
         absPrefix = prefixXPath(absPrefix || "/", selectorForIframe);
         ctxFrameId = childFrameId;
       } finally {
@@ -1004,7 +1283,11 @@ function resolveCssFocusFrameAndTail(page, rawSelector, parentByFrame, rootId) {
         parts[i],
         ctxFrameId
       );
-      if (!objectId) throw new Error("Failed to resolve iframe via CSS hop");
+      if (!objectId)
+        throw new StagehandIframeError(
+          parts[i],
+          "Failed to resolve iframe via CSS hop"
+        );
       try {
         yield parentSess.send("DOM.enable").catch(() => {
         });
@@ -1025,7 +1308,10 @@ function resolveCssFocusFrameAndTail(page, rawSelector, parentByFrame, rootId) {
           }
         }
         if (!childFrameId)
-          throw new Error("Could not map CSS iframe hop to child frameId");
+          throw new StagehandIframeError(
+            parts[i],
+            "Could not map CSS iframe hop to child frameId"
+          );
         ctxFrameId = childFrameId;
       } finally {
         yield parentSess.send("Runtime.releaseObject", { objectId }).catch(() => {
@@ -1553,6 +1839,7 @@ var init_snapshot = __esm({
   "lib/v3/understudy/a11y/snapshot.ts"() {
     init_executionContextRegistry();
     init_logger();
+    init_sdkErrors();
     IFRAME_STEP_RE = /^iframe(?:\[\d+])?$/i;
   }
 });
@@ -1981,6 +2268,7 @@ var init_locator = __esm({
     import_buffer = require("buffer");
     init_locatorScripts_generated();
     init_selectorResolver();
+    init_sdkErrors();
     Locator = class _Locator {
       constructor(frame, selector, options, nthIndex = 0) {
         this.frame = frame;
@@ -2018,7 +2306,9 @@ var init_locator = __esm({
             if (data instanceof Uint8Array) return import_buffer.Buffer.from(data);
             if (typeof data === "string") return import_buffer.Buffer.from(data);
             if (data instanceof ArrayBuffer) return import_buffer.Buffer.from(new Uint8Array(data));
-            throw new Error("Unsupported file payload buffer type");
+            throw new StagehandInvalidArgumentError(
+              "Unsupported file payload buffer type"
+            );
           };
           try {
             try {
@@ -2032,9 +2322,11 @@ var init_locator = __esm({
               );
               const ok = Boolean(res.result.value);
               if (!ok)
-                throw new Error('Target is not an <input type="file"> element');
+                throw new StagehandInvalidArgumentError(
+                  'Target is not an <input type="file"> element'
+                );
             } catch (e) {
-              throw new Error(
+              throw new StagehandInvalidArgumentError(
                 e instanceof Error ? e.message : "Unable to verify file input element"
               );
             }
@@ -2057,7 +2349,7 @@ var init_locator = __esm({
                 filePaths.push(tmp);
                 continue;
               }
-              throw new Error(
+              throw new StagehandInvalidArgumentError(
                 "Unsupported setInputFiles item \u2013 expected path or payload"
               );
             }
@@ -2123,7 +2415,7 @@ var init_locator = __esm({
               "DOM.getBoxModel",
               { objectId }
             );
-            if (!box.model) throw new Error("Element not visible (no box model)");
+            if (!box.model) throw new ElementNotVisibleError(this.selector);
             const { cx, cy } = this.centerFromBoxContent(box.model.content);
             return { x: Math.round(cx), y: Math.round(cy) };
           } finally {
@@ -2210,7 +2502,7 @@ var init_locator = __esm({
               "DOM.getBoxModel",
               { objectId }
             );
-            if (!box.model) throw new Error("Element not visible (no box model)");
+            if (!box.model) throw new ElementNotVisibleError(this.selector);
             const { cx, cy } = this.centerFromBoxContent(box.model.content);
             yield session.send("Input.dispatchMouseEvent", {
               type: "mouseMoved",
@@ -2245,7 +2537,7 @@ var init_locator = __esm({
               "DOM.getBoxModel",
               { objectId }
             );
-            if (!box.model) throw new Error("Element not visible (no box model)");
+            if (!box.model) throw new ElementNotVisibleError(this.selector);
             const { cx, cy } = this.centerFromBoxContent(box.model.content);
             yield session.send("Input.dispatchMouseEvent", {
               type: "mouseMoved",
@@ -2412,7 +2704,9 @@ var init_locator = __esm({
             }
             if (status === "error") {
               const reason = typeof (result == null ? void 0 : result.reason) === "string" && result.reason.length > 0 ? result.reason : "Failed to fill element";
-              throw new Error(`Failed to fill element (${reason})`);
+              throw new StagehandInvalidArgumentError(
+                `Failed to fill element (${reason})`
+              );
             }
             if (!status) {
               yield this.type(value);
@@ -2639,7 +2933,9 @@ var init_locator = __esm({
       nth(index) {
         const value = Number(index);
         if (!Number.isFinite(value) || value < 0) {
-          throw new Error("locator().nth() expects a non-negative index");
+          throw new StagehandInvalidArgumentError(
+            "locator().nth() expects a non-negative index"
+          );
         }
         const nextIndex = Math.floor(value);
         if (nextIndex === this.nthIndex) {
@@ -2662,7 +2958,7 @@ var init_locator = __esm({
             this.nthIndex
           );
           if (!resolved) {
-            throw new Error(`Element not found for selector: ${this.selector}`);
+            throw new StagehandElementNotFoundError([this.selector]);
           }
           return resolved;
         });
@@ -2670,7 +2966,7 @@ var init_locator = __esm({
       /** Compute a center point from a BoxModel content quad */
       centerFromBoxContent(content) {
         if (!content || content.length < 8) {
-          throw new Error("Invalid box model content quad");
+          throw new StagehandInvalidArgumentError("Invalid box model content quad");
         }
         const xs = [content[0], content[2], content[4], content[6]];
         const ys = [content[1], content[3], content[5], content[7]];
@@ -2781,6 +3077,7 @@ var FrameLocator, LocatorDelegate;
 var init_frameLocator = __esm({
   "lib/v3/understudy/frameLocator.ts"() {
     init_executionContextRegistry();
+    init_sdkErrors();
     FrameLocator = class _FrameLocator {
       constructor(page, selector, parent, root) {
         this.page = page;
@@ -2823,9 +3120,7 @@ var init_frameLocator = __esm({
               } catch (e) {
               }
             }
-            throw new Error(
-              `frameLocator: could not resolve child frame for selector: ${this.selector}`
-            );
+            throw new ContentFrameNotFoundError(this.selector);
           } finally {
             yield parentSession2.send("Runtime.releaseObject", { objectId }).catch(() => {
             });
@@ -3019,6 +3314,7 @@ var init_deepLocator = __esm({
     init_locator();
     init_logger();
     init_frameLocator();
+    init_sdkErrors();
     IFRAME_STEP_RE2 = /^iframe(?:\[\d+])?$/i;
     DeepLocatorDelegate = class _DeepLocatorDelegate {
       constructor(page, root, selector, nthIndex = 0) {
@@ -3134,7 +3430,9 @@ var init_deepLocator = __esm({
       nth(index) {
         const value = Number(index);
         if (!Number.isFinite(value) || value < 0) {
-          throw new Error("deepLocator().nth() expects a non-negative index");
+          throw new StagehandInvalidArgumentError(
+            "deepLocator().nth() expects a non-negative index"
+          );
         }
         const nextIndex = Math.floor(value);
         if (nextIndex === this.nthIndex) return this;
@@ -4049,6 +4347,15 @@ var init_consoleMessage = __esm({
 });
 
 // lib/v3/understudy/response.ts
+function isSerializableResponse(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  if (typeof candidate.requestId !== "string") return false;
+  if (!candidate.response || typeof candidate.response !== "object") {
+    return false;
+  }
+  return true;
+}
 function createDeferred() {
   let resolve3;
   let reject;
@@ -4081,7 +4388,8 @@ function parseHeadersText(headersText) {
 var Response;
 var init_response = __esm({
   "lib/v3/understudy/response.ts"() {
-    Response = class {
+    init_sdkErrors();
+    Response = class _Response {
       /**
        * Build a response wrapper from the CDP notification associated with a
        * navigation. The constructor captures the owning page/session so follow-up
@@ -4251,7 +4559,7 @@ var init_response = __esm({
             "Network.getResponseBody",
             { requestId: this.requestId }
           ).catch((error) => {
-            throw new Error(`Failed to retrieve response body: ${String(error)}`);
+            throw new ResponseBodyError(String(error));
           });
           if (result.base64Encoded) {
             return Buffer.from(result.body, "base64");
@@ -4273,7 +4581,7 @@ var init_response = __esm({
           try {
             return JSON.parse(text);
           } catch (error) {
-            throw new Error(`Failed to parse JSON response: ${String(error)}`);
+            throw new ResponseParseError(String(error));
           }
         });
       }
@@ -4308,6 +4616,33 @@ var init_response = __esm({
           this.headersObject[lower] = segments.join(", ");
         }
       }
+      /**
+       * Internal helper for creating a Response object from a Serializable
+       * goto response from the Stagehand API
+       */
+      static fromSerializable(serialized, context) {
+        var _a;
+        const reconstructed = new _Response({
+          page: context.page,
+          session: context.session,
+          requestId: serialized.requestId,
+          frameId: serialized.frameId,
+          loaderId: serialized.loaderId,
+          response: serialized.response,
+          fromServiceWorker: (_a = serialized.fromServiceWorkerFlag) != null ? _a : false
+        });
+        if (serialized.extraInfoHeaders) {
+          reconstructed.applyExtraInfo({
+            requestId: serialized.requestId,
+            headers: serialized.extraInfoHeaders,
+            headersText: serialized.extraInfoHeadersText
+          });
+        }
+        if (serialized.finishedSettled) {
+          reconstructed.markFinished(null);
+        }
+        return reconstructed;
+      }
       /** Marks the response as finished and resolves the `finished()` promise. */
       markFinished(error) {
         if (this.finishedSettled) return;
@@ -4327,6 +4662,7 @@ var Frame;
 var init_frame = __esm({
   "lib/v3/understudy/frame.ts"() {
     init_locator();
+    init_sdkErrors();
     Frame = class _Frame {
       constructor(session, frameId, pageId) {
         this.session = session;
@@ -4433,7 +4769,9 @@ var init_frame = __esm({
             }
           );
           if (res.exceptionDetails) {
-            throw new Error((_a = res.exceptionDetails.text) != null ? _a : "Evaluation failed");
+            throw new StagehandEvalError(
+              (_a = res.exceptionDetails.text) != null ? _a : "Evaluation failed"
+            );
           }
           return res.result.value;
         });
@@ -5086,6 +5424,7 @@ var init_networkManager = __esm({
 var LifecycleWatcher;
 var init_lifecycleWatcher = __esm({
   "lib/v3/understudy/lifecycleWatcher.ts"() {
+    init_sdkErrors();
     init_network();
     LifecycleWatcher = class {
       /**
@@ -5223,7 +5562,7 @@ var init_lifecycleWatcher = __esm({
       timeRemaining(deadline) {
         const remaining = deadline - Date.now();
         if (remaining <= 0) {
-          throw new Error(`Lifecycle wait timed out after ${this.timeoutMs}ms`);
+          throw new TimeoutError("Lifecycle wait", this.timeoutMs);
         }
         return remaining;
       }
@@ -5520,11 +5859,15 @@ function normalizeScreenshotClip(clip) {
   const height = Number(clip.height);
   for (const [key, value] of Object.entries({ x, y, width, height })) {
     if (!Number.isFinite(value)) {
-      throw new Error(`screenshot: clip.${key} must be a finite number`);
+      throw new StagehandInvalidArgumentError(
+        `screenshot: clip.${key} must be a finite number`
+      );
     }
   }
   if (width <= 0 || height <= 0) {
-    throw new Error("screenshot: clip width/height must be positive");
+    throw new StagehandInvalidArgumentError(
+      "screenshot: clip width/height must be positive"
+    );
   }
   return { x, y, width, height };
 }
@@ -5813,6 +6156,7 @@ function withScreenshotTimeout(timeoutMs, task) {
 }
 var init_screenshotUtils = __esm({
   "lib/v3/understudy/screenshotUtils.ts"() {
+    init_sdkErrors();
   }
 });
 
@@ -5834,7 +6178,9 @@ var init_page = __esm({
     init_networkManager();
     init_lifecycleWatcher();
     init_navigationResponseTracker();
+    init_response();
     init_consoleMessage();
+    init_sdkErrors();
     init_screenshotUtils();
     LIFECYCLE_NAME = {
       load: "load",
@@ -6151,7 +6497,7 @@ var init_page = __esm({
       }
       on(event, listener) {
         if (event !== "console") {
-          throw new Error(`Unsupported event: ${event}`);
+          throw new StagehandInvalidArgumentError(`Unsupported event: ${event}`);
         }
         const firstListener = this.consoleListeners.size === 0;
         this.consoleListeners.add(listener);
@@ -6162,7 +6508,7 @@ var init_page = __esm({
       }
       once(event, listener) {
         if (event !== "console") {
-          throw new Error(`Unsupported event: ${event}`);
+          throw new StagehandInvalidArgumentError(`Unsupported event: ${event}`);
         }
         const wrapper = (message) => {
           this.off("console", wrapper);
@@ -6172,7 +6518,7 @@ var init_page = __esm({
       }
       off(event, listener) {
         if (event !== "console") {
-          throw new Error(`Unsupported event: ${event}`);
+          throw new StagehandInvalidArgumentError(`Unsupported event: ${event}`);
         }
         this.consoleListeners.delete(listener);
         if (this.consoleListeners.size === 0) {
@@ -6361,13 +6707,19 @@ var init_page = __esm({
           });
           try {
             if (this.apiClient) {
-              yield this.apiClient.goto(
+              const result = yield this.apiClient.goto(
                 url,
                 { waitUntil: options == null ? void 0 : options.waitUntil },
                 this.mainFrameId()
               );
               this._currentUrl = url;
-              return null;
+              if (isSerializableResponse(result)) {
+                return Response.fromSerializable(result, {
+                  page: this,
+                  session: this.mainSession
+                });
+              }
+              return result;
             }
             const response = yield this.mainSession.send(
               "Page.navigate",
@@ -6592,13 +6944,17 @@ var init_page = __esm({
           const opts = options != null ? options : {};
           const type = (_a = opts.type) != null ? _a : "png";
           if (type !== "png" && type !== "jpeg") {
-            throw new Error(`screenshot: unsupported image type "${type}"`);
+            throw new StagehandInvalidArgumentError(
+              `screenshot: unsupported image type "${type}"`
+            );
           }
           if (opts.fullPage && opts.clip) {
-            throw new Error("screenshot: clip and fullPage cannot be used together");
+            throw new StagehandInvalidArgumentError(
+              "screenshot: clip and fullPage cannot be used together"
+            );
           }
           if (type === "png" && typeof opts.quality === "number") {
-            throw new Error(
+            throw new StagehandInvalidArgumentError(
               'screenshot: quality option is only valid for type="jpeg"'
             );
           }
@@ -6735,7 +7091,7 @@ var init_page = __esm({
           );
           if (exceptionDetails) {
             const msg = exceptionDetails.text || ((_a = exceptionDetails.exception) == null ? void 0 : _a.description) || "Evaluation failed";
-            throw new Error(msg);
+            throw new StagehandEvalError(msg);
           }
           return result == null ? void 0 : result.value;
         });
@@ -7374,9 +7730,12 @@ __export(v3_exports, {
   AnnotatedScreenshotText: () => AnnotatedScreenshotText,
   BrowserbaseSessionNotFoundError: () => BrowserbaseSessionNotFoundError,
   CaptchaTimeoutError: () => CaptchaTimeoutError,
+  ConnectionTimeoutError: () => ConnectionTimeoutError,
   ConsoleMessage: () => ConsoleMessage,
   ContentFrameNotFoundError: () => ContentFrameNotFoundError,
   CreateChatCompletionResponseError: () => CreateChatCompletionResponseError,
+  CuaModelRequiredError: () => CuaModelRequiredError,
+  ElementNotVisibleError: () => ElementNotVisibleError,
   ExperimentalApiConflictError: () => ExperimentalApiConflictError,
   ExperimentalNotConfiguredError: () => ExperimentalNotConfiguredError,
   HandlerNotInitializedError: () => HandlerNotInitializedError,
@@ -7387,7 +7746,10 @@ __export(v3_exports, {
   MCPConnectionError: () => MCPConnectionError,
   MissingEnvironmentVariableError: () => MissingEnvironmentVariableError,
   MissingLLMConfigurationError: () => MissingLLMConfigurationError,
+  PageNotFoundError: () => PageNotFoundError,
   Response: () => Response,
+  ResponseBodyError: () => ResponseBodyError,
+  ResponseParseError: () => ResponseParseError,
   Stagehand: () => V3,
   StagehandAPIError: () => StagehandAPIError,
   StagehandAPIUnauthorizedError: () => StagehandAPIUnauthorizedError,
@@ -7410,6 +7772,7 @@ __export(v3_exports, {
   StagehandShadowRootMissingError: () => StagehandShadowRootMissingError,
   StagehandShadowSegmentEmptyError: () => StagehandShadowSegmentEmptyError,
   StagehandShadowSegmentNotFoundError: () => StagehandShadowSegmentNotFoundError,
+  TimeoutError: () => TimeoutError,
   UnsupportedAISDKModelProviderError: () => UnsupportedAISDKModelProviderError,
   UnsupportedModelError: () => UnsupportedModelError,
   UnsupportedModelProviderError: () => UnsupportedModelProviderError,
@@ -7442,231 +7805,8 @@ var import_os2 = __toESM(require("os"));
 var import_path5 = __toESM(require("path"));
 var import_process2 = __toESM(require("process"));
 
-// lib/version.ts
-var STAGEHAND_VERSION = "3.0.1";
-
-// lib/v3/types/public/sdkErrors.ts
-var StagehandError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = this.constructor.name;
-  }
-};
-var StagehandDefaultError = class extends StagehandError {
-  constructor(error) {
-    if (error instanceof Error || error instanceof StagehandError) {
-      super(
-        `
-Hey! We're sorry you ran into an error. 
-Stagehand version: ${STAGEHAND_VERSION} 
-If you need help, please open a Github issue or reach out to us on Slack: https://stagehand.dev/slack
-
-Full error:
-${error.message}`
-      );
-    }
-  }
-};
-var StagehandEnvironmentError = class extends StagehandError {
-  constructor(currentEnvironment, requiredEnvironment, feature) {
-    super(
-      `You seem to be setting the current environment to ${currentEnvironment}.Ensure the environment is set to ${requiredEnvironment} if you want to use ${feature}.`
-    );
-  }
-};
-var MissingEnvironmentVariableError = class extends StagehandError {
-  constructor(missingEnvironmentVariable, feature) {
-    super(
-      `${missingEnvironmentVariable} is required to use ${feature}.Please set ${missingEnvironmentVariable} in your environment.`
-    );
-  }
-};
-var UnsupportedModelError = class extends StagehandError {
-  constructor(supportedModels, feature) {
-    super(
-      feature ? `${feature} requires one of the following models: ${supportedModels}` : `please use one of the supported models: ${supportedModels}`
-    );
-  }
-};
-var UnsupportedModelProviderError = class extends StagehandError {
-  constructor(supportedProviders, feature) {
-    super(
-      feature ? `${feature} requires one of the following model providers: ${supportedProviders}` : `please use one of the supported model providers: ${supportedProviders}`
-    );
-  }
-};
-var UnsupportedAISDKModelProviderError = class extends StagehandError {
-  constructor(provider, supportedProviders) {
-    super(
-      `${provider} is not currently supported for aiSDK. please use one of the supported model providers: ${supportedProviders}`
-    );
-  }
-};
-var InvalidAISDKModelFormatError = class extends StagehandError {
-  constructor(modelName) {
-    super(
-      `${modelName} does not follow correct format for specifying aiSDK models. Please define your model as 'provider/model-name'. For example: \`model: 'openai/gpt-4o-mini'\``
-    );
-  }
-};
-var StagehandNotInitializedError = class extends StagehandError {
-  constructor(prop) {
-    super(
-      `You seem to be calling \`${prop}\` on a page in an uninitialized \`Stagehand\` object. Ensure you are running \`await stagehand.init()\` on the Stagehand object before referencing the \`page\` object.`
-    );
-  }
-};
-var BrowserbaseSessionNotFoundError = class extends StagehandError {
-  constructor() {
-    super("No Browserbase session ID found");
-  }
-};
-var CaptchaTimeoutError = class extends StagehandError {
-  constructor() {
-    super("Captcha timeout");
-  }
-};
-var MissingLLMConfigurationError = class extends StagehandError {
-  constructor() {
-    super(
-      "No LLM API key or LLM Client configured. An LLM API key or a custom LLM Client is required to use act, extract, or observe."
-    );
-  }
-};
-var HandlerNotInitializedError = class extends StagehandError {
-  constructor(handlerType) {
-    super(`${handlerType} handler not initialized`);
-  }
-};
-var StagehandInvalidArgumentError = class extends StagehandError {
-  constructor(message) {
-    super(`InvalidArgumentError: ${message}`);
-  }
-};
-var StagehandElementNotFoundError = class extends StagehandError {
-  constructor(xpaths) {
-    super(`Could not find an element for the given xPath(s): ${xpaths}`);
-  }
-};
-var AgentScreenshotProviderError = class extends StagehandError {
-  constructor(message) {
-    super(`ScreenshotProviderError: ${message}`);
-  }
-};
-var StagehandMissingArgumentError = class extends StagehandError {
-  constructor(message) {
-    super(`MissingArgumentError: ${message}`);
-  }
-};
-var CreateChatCompletionResponseError = class extends StagehandError {
-  constructor(message) {
-    super(`CreateChatCompletionResponseError: ${message}`);
-  }
-};
-var StagehandEvalError = class extends StagehandError {
-  constructor(message) {
-    super(`StagehandEvalError: ${message}`);
-  }
-};
-var StagehandDomProcessError = class extends StagehandError {
-  constructor(message) {
-    super(`Error Processing Dom: ${message}`);
-  }
-};
-var StagehandClickError = class extends StagehandError {
-  constructor(message, selector) {
-    super(
-      `Error Clicking Element with selector: ${selector} Reason: ${message}`
-    );
-  }
-};
-var LLMResponseError = class extends StagehandError {
-  constructor(primitive, message) {
-    super(`${primitive} LLM response error: ${message}`);
-  }
-};
-var StagehandIframeError = class extends StagehandError {
-  constructor(frameUrl, message) {
-    super(
-      `Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`
-    );
-  }
-};
-var ContentFrameNotFoundError = class extends StagehandError {
-  constructor(selector) {
-    super(`Unable to obtain a content frame for selector: ${selector}`);
-  }
-};
-var XPathResolutionError = class extends StagehandError {
-  constructor(xpath) {
-    super(`XPath "${xpath}" does not resolve in the current page or frames`);
-  }
-};
-var ExperimentalApiConflictError = class extends StagehandError {
-  constructor() {
-    super(
-      "`experimental` mode cannot be used together with the Stagehand API. To use experimental features, set experimental: true, and useApi: false in the stagehand constructor. To use the Stagehand API, set experimental: false and useApi: true in the stagehand constructor. "
-    );
-  }
-};
-var ExperimentalNotConfiguredError = class extends StagehandError {
-  constructor(featureName) {
-    super(`Feature "${featureName}" is an experimental feature, and cannot be configured when useAPI: true. 
-    Please set experimental: true and useAPI: false in the stagehand constructor to use this feature. 
-    If you wish to use the Stagehand API, please ensure ${featureName} is not defined in your function call, 
-    and set experimental: false, useAPI: true in the Stagehand constructor. `);
-  }
-};
-var ZodSchemaValidationError = class extends Error {
-  constructor(received, issues) {
-    super(`Zod schema validation failed
-
-\u2014 Received \u2014
-${JSON.stringify(received, null, 2)}
-
-\u2014 Issues \u2014
-${JSON.stringify(issues, null, 2)}`);
-    this.received = received;
-    this.issues = issues;
-    this.name = "ZodSchemaValidationError";
-  }
-};
-var StagehandInitError = class extends StagehandError {
-  constructor(message) {
-    super(message);
-  }
-};
-var MCPConnectionError = class extends StagehandError {
-  constructor(serverUrl, originalError) {
-    const errorMessage = originalError instanceof Error ? originalError.message : String(originalError);
-    super(
-      `Failed to connect to MCP server at "${serverUrl}". ${errorMessage}. Please verify the server URL is correct and the server is running.`
-    );
-    this.serverUrl = serverUrl;
-    this.originalError = originalError;
-  }
-};
-var StagehandShadowRootMissingError = class extends StagehandError {
-  constructor(detail) {
-    super(
-      `No shadow root present on the resolved host` + (detail ? `: ${detail}` : "")
-    );
-  }
-};
-var StagehandShadowSegmentEmptyError = class extends StagehandError {
-  constructor() {
-    super(`Empty selector segment after shadow-DOM hop ("//")`);
-  }
-};
-var StagehandShadowSegmentNotFoundError = class extends StagehandError {
-  constructor(segment, hint) {
-    super(
-      `Shadow segment '${segment}' matched no element inside shadow root` + (hint ? ` ${hint}` : "")
-    );
-  }
-};
-
 // lib/utils.ts
+init_sdkErrors();
 var import_genai = require("@google/genai");
 var import_v3 = require("zod/v3");
 var ID_PATTERN = /^\d+-\d+$/;
@@ -8326,6 +8466,7 @@ function safeGetPageUrl(page) {
 }
 
 // lib/v3/cache/ActCache.ts
+init_sdkErrors();
 var ActCache = class {
   constructor({
     storage,
@@ -8453,7 +8594,7 @@ var ActCache = class {
     return __async(this, null, function* () {
       const handler = this.getActHandler();
       if (!handler) {
-        throw new Error("V3 not initialized. Call init() before act().");
+        throw new StagehandNotInitializedError("act()");
       }
       const execute = () => __async(this, null, function* () {
         var _a, _b, _c;
@@ -9700,12 +9841,14 @@ var SupportedPlaywrightAction = /* @__PURE__ */ ((SupportedPlaywrightAction2) =>
   SupportedPlaywrightAction2["NEXT_CHUNK"] = "nextChunk";
   SupportedPlaywrightAction2["PREV_CHUNK"] = "prevChunk";
   SupportedPlaywrightAction2["SELECT_OPTION_FROM_DROPDOWN"] = "selectOptionFromDropdown";
+  SupportedPlaywrightAction2["HOVER"] = "hover";
   return SupportedPlaywrightAction2;
 })(SupportedPlaywrightAction || {});
 
 // lib/v3/handlers/handlerUtils/actHandlerUtils.ts
 init_deepLocator();
 init_logger();
+init_sdkErrors();
 var UnderstudyCommandException = class extends Error {
   constructor(message) {
     super(message);
@@ -9810,7 +9953,8 @@ var METHOD_HANDLER_MAP = {
   nextChunk: scrollToNextChunk,
   prevChunk: scrollToPreviousChunk,
   selectOptionFromDropdown: selectOption,
-  selectOption
+  selectOption,
+  hover
 };
 function selectOption(ctx) {
   return __async(this, null, function* () {
@@ -10153,6 +10297,26 @@ function scrollByElementHeight(ctx, direction) {
     }
   });
 }
+function hover(ctx) {
+  return __async(this, null, function* () {
+    const { locator, xpath } = ctx;
+    try {
+      yield locator.hover();
+    } catch (e) {
+      v3Logger({
+        category: "action",
+        message: "error attempting to hover",
+        level: 0,
+        auxiliary: {
+          error: { value: e.message, type: "string" },
+          trace: { value: e.stack, type: "string" },
+          xpath: { value: xpath, type: "string" }
+        }
+      });
+      throw new UnderstudyCommandException(e.message);
+    }
+  });
+}
 function getFrameUrl(frame) {
   return __async(this, null, function* () {
     const url = yield frame.evaluate("location.href");
@@ -10661,6 +10825,7 @@ var ActHandler = class {
 init_logger();
 init_snapshot();
 var import_v34 = require("zod/v3");
+init_sdkErrors();
 function transformUrlStringsToNumericIds(schema) {
   const [finalSchema, urlPaths] = transformSchema(schema, []);
   return [finalSchema, urlPaths];
@@ -10693,7 +10858,7 @@ var ExtractHandler = class {
           return pageTextSchema.parse(result);
         }
         if (!instruction && schema) {
-          throw new Error(
+          throw new StagehandInvalidArgumentError(
             "extract() requires an instruction when a schema is provided."
           );
         }
@@ -11452,6 +11617,7 @@ function createStandardAction(toolCallName, toolResult, args, reasoning) {
 }
 
 // lib/v3/handlers/v3AgentHandler.ts
+init_sdkErrors();
 var V3AgentHandler = class {
   constructor(v3, logger, llmClient, executionModel, systemInstructions, mcpTools) {
     this.v3 = v3;
@@ -11483,9 +11649,7 @@ var V3AgentHandler = class {
           { role: "user", content: options.instruction }
         ];
         if (!((_a = this.llmClient) == null ? void 0 : _a.getLanguageModel)) {
-          throw new Error(
-            "V3AgentHandler requires an AISDK-backed LLM client. Ensure your model is configured like 'openai/gpt-4.1-mini'."
-          );
+          throw new MissingLLMConfigurationError();
         }
         const baseModel = this.llmClient.getLanguageModel();
         const wrappedModel = (0, import_ai11.wrapLanguageModel)({
@@ -11632,7 +11796,11 @@ STRATEGY:
 // lib/v3/handlers/v3CuaAgentHandler.ts
 init_snapshot();
 
+// lib/v3/agent/AgentProvider.ts
+init_sdkErrors();
+
 // lib/v3/agent/AnthropicCUAClient.ts
+init_sdkErrors();
 var import_sdk = __toESM(require("@anthropic-ai/sdk"));
 var import_zod_to_json_schema = require("zod-to-json-schema");
 
@@ -12525,6 +12693,7 @@ var AnthropicCUAClient = class extends AgentClient {
 
 // lib/v3/agent/OpenAICUAClient.ts
 var import_openai = __toESM(require("openai"));
+init_sdkErrors();
 var OpenAICUAClient = class extends AgentClient {
   constructor(type, modelName, userProvidedInstructions, clientOptions, tools) {
     super(type, modelName, userProvidedInstructions);
@@ -12998,6 +13167,7 @@ var OpenAICUAClient = class extends AgentClient {
 
 // lib/v3/agent/GoogleCUAClient.ts
 var import_genai3 = require("@google/genai");
+init_sdkErrors();
 
 // lib/v3/agent/utils/googleCustomToolHandler.ts
 var import_genai2 = require("@google/genai");
@@ -13314,7 +13484,7 @@ var GoogleCUAClient = class extends AgentClient {
               config: this.generateContentConfig
             });
             if (!response.candidates || response.candidates.length === 0) {
-              throw new Error("Response has no candidates!");
+              throw new LLMResponseError("agent", "Response has no candidates!");
             }
             break;
           } catch (error) {
@@ -14314,6 +14484,7 @@ var V3CuaAgentHandler = class {
 
 // lib/v3/launch/browserbase.ts
 var import_sdk2 = __toESM(require("@browserbasehq/sdk"));
+init_sdkErrors();
 function createBrowserbaseSession(apiKey, projectId, params, resumeSessionId) {
   return __async(this, null, function* () {
     var _b;
@@ -14323,11 +14494,11 @@ function createBrowserbaseSession(apiKey, projectId, params, resumeSessionId) {
         resumeSessionId
       );
       if (!(existing == null ? void 0 : existing.id)) {
-        throw new Error(`Browserbase session not found: ${resumeSessionId}`);
+        throw new BrowserbaseSessionNotFoundError();
       }
       const ws = existing.connectUrl;
       if (!ws) {
-        throw new Error(
+        throw new StagehandInitError(
           `Browserbase session resume missing connectUrl for ${resumeSessionId}`
         );
       }
@@ -14354,7 +14525,7 @@ function createBrowserbaseSession(apiKey, projectId, params, resumeSessionId) {
     });
     const created = yield bb.sessions.create(createPayload);
     if (!(created == null ? void 0 : created.connectUrl) || !(created == null ? void 0 : created.id)) {
-      throw new Error(
+      throw new StagehandInitError(
         "Browserbase session creation returned an unexpected shape."
       );
     }
@@ -15405,6 +15576,7 @@ var Launcher = class _Launcher {
 };
 
 // lib/v3/launch/local.ts
+init_sdkErrors();
 function launchLocalChrome(opts) {
   return __async(this, null, function* () {
     var _a, _b, _c;
@@ -15449,12 +15621,15 @@ function waitForWebSocketDebuggerUrl(port, timeoutMs) {
       }
       yield new Promise((r) => setTimeout(r, 250));
     }
-    throw new Error(
+    throw new ConnectionTimeoutError(
       `Timed out waiting for /json/version on port ${port}${lastErrMsg ? ` (last error: ${lastErrMsg})` : ""}`
     );
   });
 }
 
+// lib/v3/llm/LLMProvider.ts
+init_sdkErrors();
+
 // lib/v3/llm/aisdk.ts
 var import_ai13 = require("ai");
 
@@ -15727,6 +15902,7 @@ var AISdkClient = class extends LLMClient {
 // lib/v3/llm/AnthropicClient.ts
 var import_sdk3 = __toESM(require("@anthropic-ai/sdk"));
 var import_zod_to_json_schema3 = require("zod-to-json-schema");
+init_sdkErrors();
 var AnthropicClient = class extends LLMClient {
   constructor({
     modelName,
@@ -15969,6 +16145,7 @@ var extractSchemaProperties = (jsonSchema2) => {
 // lib/v3/llm/CerebrasClient.ts
 var import_openai2 = __toESM(require("openai"));
 var import_zod_to_json_schema4 = require("zod-to-json-schema");
+init_sdkErrors();
 var CerebrasClient = class extends LLMClient {
   constructor({
     modelName,
@@ -16188,6 +16365,7 @@ var CerebrasClient = class extends LLMClient {
 
 // lib/v3/llm/GoogleClient.ts
 var import_genai4 = require("@google/genai");
+init_sdkErrors();
 var roleMap = {
   user: "user",
   assistant: "model",
@@ -16556,6 +16734,7 @@ ${firstPartText.text}`;
 // lib/v3/llm/GroqClient.ts
 var import_openai3 = __toESM(require("openai"));
 var import_zod_to_json_schema5 = require("zod-to-json-schema");
+init_sdkErrors();
 var GroqClient = class extends LLMClient {
   constructor({
     modelName,
@@ -16777,6 +16956,7 @@ var GroqClient = class extends LLMClient {
 var import_openai4 = __toESM(require("openai"));
 var import_zod = require("openai/helpers/zod");
 var import_zod_to_json_schema6 = __toESM(require("zod-to-json-schema"));
+init_sdkErrors();
 var OpenAIClient = class extends LLMClient {
   constructor({
     modelName,
@@ -38400,6 +38580,7 @@ init_logger();
 var import_client = require("@modelcontextprotocol/sdk/client/index.js");
 var import_streamableHttp = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/client/stdio.js");
+init_sdkErrors();
 var connectToMCPServer = (serverConfig) => __async(null, null, function* () {
   try {
     let transport;
@@ -38525,6 +38706,9 @@ var LOG_LEVEL_NAMES = {
 init_consoleMessage();
 init_response();
 
+// lib/v3/types/public/index.ts
+init_sdkErrors();
+
 // examples/external_clients/aisdk.ts
 var import_ai14 = require("ai");
 var AISdkClient2 = class extends LLMClient {
@@ -38892,6 +39076,7 @@ function installV3PiercerIntoSession(session) {
 
 // lib/v3/understudy/context.ts
 init_executionContextRegistry();
+init_sdkErrors();
 function isTopLevelPage(info) {
   const ti = info;
   return info.type === "page" && ti.subtype !== "iframe";
@@ -38927,7 +39112,6 @@ var V3Context = class _V3Context {
     return __async(this, null, function* () {
       var _a, _b, _c;
       const conn = yield CdpConnection.connect(wsUrl);
-      yield conn.enableAutoAttach();
       const ctx = new _V3Context(
         conn,
         (_a = opts == null ? void 0 : opts.env) != null ? _a : "LOCAL",
@@ -38955,11 +39139,41 @@ var V3Context = class _V3Context {
         }
         yield new Promise((r) => setTimeout(r, 25));
       }
-      throw new Error(
-        `waitForFirstTopLevelPage timed out after ${timeoutMs}ms (no top-level Page)`
+      throw new TimeoutError(
+        "waitForFirstTopLevelPage (no top-level Page)",
+        timeoutMs
       );
     });
   }
+  waitForInitialTopLevelTargets(targetIds, timeoutMs = 3e3) {
+    return __async(this, null, function* () {
+      if (!targetIds.length) return;
+      const pending = new Set(targetIds);
+      const deadline = Date.now() + timeoutMs;
+      while (pending.size && Date.now() < deadline) {
+        for (const tid of Array.from(pending)) {
+          if (this.pagesByTarget.has(tid)) {
+            pending.delete(tid);
+          }
+        }
+        if (!pending.size) return;
+        yield new Promise((r) => setTimeout(r, 25));
+      }
+      if (pending.size) {
+        v3Logger({
+          category: "ctx",
+          message: "Timed out waiting for existing top-level targets to attach",
+          level: 2,
+          auxiliary: {
+            remainingTargets: {
+              value: JSON.stringify(Array.from(pending)),
+              type: "object"
+            }
+          }
+        });
+      }
+    });
+  }
   ensurePiercer(session) {
     return __async(this, null, function* () {
       const key = this.sessionKey(session);
@@ -39049,8 +39263,7 @@ var V3Context = class _V3Context {
   getFullFrameTreeByMainFrameId(rootMainFrameId) {
     return __async(this, null, function* () {
       const owner = this.resolvePageByMainFrameId(rootMainFrameId);
-      if (!owner)
-        throw new Error(`No Page found for mainFrameId=${rootMainFrameId}`);
+      if (!owner) throw new PageNotFoundError(`mainFrameId=${rootMainFrameId}`);
       return owner.asProtocolFrameTree(rootMainFrameId);
     });
   }
@@ -39073,7 +39286,7 @@ var V3Context = class _V3Context {
         if (page) return page;
         yield new Promise((r) => setTimeout(r, 25));
       }
-      throw new Error(`newPage timeout: target not attached (${targetId})`);
+      throw new TimeoutError(`newPage: target not attached (${targetId})`, 5e3);
     });
   }
   /**
@@ -39141,6 +39354,7 @@ var V3Context = class _V3Context {
           }
         })
       );
+      yield this.conn.enableAutoAttach();
       const targets = yield this.conn.getTargets();
       for (const t of targets) {
         try {
@@ -39148,6 +39362,8 @@ var V3Context = class _V3Context {
         } catch (e) {
         }
       }
+      const topLevelTargetIds = targets.filter((t) => isTopLevelPage(t)).map((t) => t.targetId);
+      yield this.waitForInitialTopLevelTargets(topLevelTargetIds);
     });
   }
   /**
@@ -39433,7 +39649,7 @@ var V3Context = class _V3Context {
         yield new Promise((r) => setTimeout(r, 25));
       }
       if (immediate) return immediate;
-      throw new Error("awaitActivePage: no page available");
+      throw new PageNotFoundError("awaitActivePage: no page available");
     });
   }
 };
@@ -39464,6 +39680,7 @@ function resolveModel(model) {
 // lib/v3/api.ts
 var import_fetch_cookie = __toESM(require("fetch-cookie"));
 var import_zod_to_json_schema7 = __toESM(require("zod-to-json-schema"));
+init_version();
 var StagehandAPIClient = class {
   constructor({ apiKey, projectId, logger }) {
     this.apiKey = apiKey;
@@ -39608,9 +39825,7 @@ var StagehandAPIClient = class {
   agentExecute(agentConfig, executeOptions, frameId) {
     return __async(this, null, function* () {
       if (agentConfig.integrations && agentConfig.integrations.length > 0) {
-        throw new StagehandAPIError(
-          "MCP integrations are not supported in API mode. Set experimental: true to use MCP integrations."
-        );
+        throw new ExperimentalNotConfiguredError("MCP integrations");
       }
       if (typeof executeOptions === "object") {
         if (executeOptions.page) {
@@ -39839,7 +40054,7 @@ function resolveModelConfiguration(model) {
   if (model && typeof model === "object") {
     const _a = model, { modelName } = _a, clientOptions = __objRest(_a, ["modelName"]);
     if (!modelName) {
-      throw new Error(
+      throw new StagehandInvalidArgumentError(
         "model.modelName is required when providing client options."
       );
     }
@@ -39919,6 +40134,9 @@ var _V3 = class _V3 {
     this.llmProvider = new LLMProvider(this.logger);
     this.domSettleTimeoutMs = opts.domSettleTimeout;
     this.disableAPI = (_g = opts.disableAPI) != null ? _g : false;
+    if (this.experimental && !this.disableAPI) {
+      throw new ExperimentalApiConflictError();
+    }
     const baseClientOptions = clientOptions ? __spreadValues({}, clientOptions) : {};
     if (opts.llmClient) {
       this.llmClient = opts.llmClient;
@@ -40339,8 +40557,9 @@ var _V3 = class _V3 {
           if (this.opts.env === "BROWSERBASE") {
             const { apiKey, projectId } = this.requireBrowserbaseCreds();
             if (!apiKey || !projectId) {
-              throw new Error(
-                "BROWSERBASE credentials missing. Provide in your v3 constructor, or set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID in your .env"
+              throw new MissingEnvironmentVariableError(
+                "BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID",
+                "Browserbase environment"
               );
             }
             this.logger({
@@ -40419,7 +40638,7 @@ var _V3 = class _V3 {
             return;
           }
           const neverEnv = this.opts.env;
-          throw new Error(`Unsupported env: ${neverEnv}`);
+          throw new StagehandInitError(`Unsupported env: ${neverEnv}`);
         }));
       } catch (error) {
         if (this.externalLogger) {
@@ -40468,8 +40687,7 @@ var _V3 = class _V3 {
   act(input, options) {
     return __async(this, null, function* () {
       return yield withInstanceLogContext(this.instanceId, () => __async(this, null, function* () {
-        if (!this.actHandler)
-          throw new Error("V3 not initialized. Call init() before act().");
+        if (!this.actHandler) throw new StagehandNotInitializedError("act()");
         let actResult;
         if (isObserveResult(input)) {
           const v3Page = yield this.resolvePage(options == null ? void 0 : options.page);
@@ -40500,7 +40718,7 @@ var _V3 = class _V3 {
           return actResult;
         }
         if (typeof input !== "string" || !input.trim()) {
-          throw new Error(
+          throw new StagehandInvalidArgumentError(
             "act(): instruction string is required unless passing an Action"
           );
         }
@@ -40567,7 +40785,7 @@ var _V3 = class _V3 {
     return __async(this, null, function* () {
       return yield withInstanceLogContext(this.instanceId, () => __async(this, null, function* () {
         if (!this.extractHandler) {
-          throw new Error("V3 not initialized. Call init() before extract().");
+          throw new StagehandNotInitializedError("extract()");
         }
         let instruction;
         let schema;
@@ -40585,7 +40803,9 @@ var _V3 = class _V3 {
           options = a || void 0;
         }
         if (!instruction && schema) {
-          throw new Error("extract(): schema provided without instruction");
+          throw new StagehandInvalidArgumentError(
+            "extract(): schema provided without instruction"
+          );
         }
         const effectiveSchema = instruction && !schema ? defaultExtractSchema : schema;
         const page = yield this.resolvePage(options == null ? void 0 : options.page);
@@ -40617,7 +40837,7 @@ var _V3 = class _V3 {
     return __async(this, null, function* () {
       return yield withInstanceLogContext(this.instanceId, () => __async(this, null, function* () {
         if (!this.observeHandler) {
-          throw new Error("V3 not initialized. Call init() before observe().");
+          throw new StagehandNotInitializedError("observe()");
         }
         let instruction;
         let options;
@@ -40661,7 +40881,7 @@ var _V3 = class _V3 {
   /** Return the browser-level CDP WebSocket endpoint. */
   connectURL() {
     if (this.state.kind === "UNINITIALIZED") {
-      throw new Error("V3 not initialized. Call await v3.init() first.");
+      throw new StagehandNotInitializedError("connectURL()");
     }
     return this.state.ws;
   }
@@ -40726,10 +40946,9 @@ var _V3 = class _V3 {
       const missing = [];
       if (!apiKey) missing.push("BROWSERBASE_API_KEY");
       if (!projectId) missing.push("BROWSERBASE_PROJECT_ID");
-      throw new Error(
-        `BROWSERBASE credentials missing. Provide in your v3 constructor, or set ${missing.join(
-          ", "
-        )} in your .env`
+      throw new MissingEnvironmentVariableError(
+        missing.join(", "),
+        "Browserbase"
       );
     }
     this.opts.apiKey = apiKey;
@@ -40775,7 +40994,9 @@ var _V3 = class _V3 {
         });
         return frameTree.frame.id;
       }
-      throw new Error("Unsupported page object passed to V3.act()");
+      throw new StagehandInvalidArgumentError(
+        "Unsupported page object passed to V3.act()"
+      );
     });
   }
   isPlaywrightPage(p) {
@@ -40795,9 +41016,7 @@ var _V3 = class _V3 {
       }
       const ctx = this.ctx;
       if (!ctx) {
-        throw new Error(
-          "V3 context not initialized. Call init() before resolving pages."
-        );
+        throw new StagehandNotInitializedError("resolvePage()");
       }
       return yield ctx.awaitActivePage();
     });
@@ -40811,24 +41030,30 @@ var _V3 = class _V3 {
         const frameId = yield this.resolveTopFrameId(input);
         const page = this.ctx.resolvePageByMainFrameId(frameId);
         if (!page)
-          throw new Error("Failed to resolve V3 Page from Playwright page.");
+          throw new StagehandInitError(
+            "Failed to resolve V3 Page from Playwright page."
+          );
         return page;
       }
       if (this.isPatchrightPage(input)) {
         const frameId = yield this.resolveTopFrameId(input);
         const page = this.ctx.resolvePageByMainFrameId(frameId);
         if (!page)
-          throw new Error("Failed to resolve V3 Page from Playwright page.");
+          throw new StagehandInitError(
+            "Failed to resolve V3 Page from Patchright page."
+          );
         return page;
       }
       if (this.isPuppeteerPage(input)) {
         const frameId = yield this.resolveTopFrameId(input);
         const page = this.ctx.resolvePageByMainFrameId(frameId);
         if (!page)
-          throw new Error("Failed to resolve V3 Page from Puppeteer page.");
+          throw new StagehandInitError(
+            "Failed to resolve V3 Page from Puppeteer page."
+          );
         return page;
       }
-      throw new Error("Unsupported page object.");
+      throw new StagehandInvalidArgumentError("Unsupported page object.");
     });
   }
   /**
@@ -40855,8 +41080,8 @@ var _V3 = class _V3 {
     });
     if (options == null ? void 0 : options.cua) {
       if (((options == null ? void 0 : options.integrations) || (options == null ? void 0 : options.tools)) && !this.experimental) {
-        throw new Error(
-          "MCP integrations and custom tools are experimental. Enable experimental: true in V3 options."
+        throw new ExperimentalNotConfiguredError(
+          "MCP integrations and custom tools"
         );
       }
       const modelToUse = (options == null ? void 0 : options.model) || __spreadValues({
@@ -40864,9 +41089,7 @@ var _V3 = class _V3 {
       }, this.modelClientOptions);
       const { modelName, isCua, clientOptions } = resolveModel(modelToUse);
       if (!isCua) {
-        throw new Error(
-          "To use the computer use agent, please provide a CUA model in the agent constructor or stagehand config. Try one of our supported CUA models: " + AVAILABLE_CUA_MODELS.join(", ")
-        );
+        throw new CuaModelRequiredError(AVAILABLE_CUA_MODELS);
       }
       const agentConfigSignature2 = this.agentCache.buildConfigSignature(options);
       return {
@@ -40874,9 +41097,7 @@ var _V3 = class _V3 {
           return withInstanceLogContext(this.instanceId, () => __async(this, null, function* () {
             var _a2, _b2;
             if ((options == null ? void 0 : options.integrations) && !this.experimental) {
-              throw new Error(
-                "MCP integrations are experimental. Enable experimental: true in V3 options."
-              );
+              throw new ExperimentalNotConfiguredError("MCP integrations");
             }
             const tools = (options == null ? void 0 : options.integrations) ? yield resolveTools(options.integrations, options.tools) : (_a2 = options == null ? void 0 : options.tools) != null ? _a2 : {};
             const handler = new V3CuaAgentHandler(
@@ -40957,8 +41178,8 @@ Do not ask follow up questions, the user will trust your judgement.`
         return withInstanceLogContext(this.instanceId, () => __async(this, null, function* () {
           var _a2, _b2;
           if (((options == null ? void 0 : options.integrations) || (options == null ? void 0 : options.tools)) && !this.experimental) {
-            throw new Error(
-              "MCP integrations and custom tools are experimental. Enable experimental: true in V3 options."
+            throw new ExperimentalNotConfiguredError(
+              "MCP integrations and custom tools"
             );
           }
           const tools = (options == null ? void 0 : options.integrations) ? yield resolveTools(options.integrations, options.tools) : (_a2 = options == null ? void 0 : options.tools) != null ? _a2 : {};
@@ -41043,6 +41264,7 @@ function isObserveResult(v) {
 // lib/v3Evaluator.ts
 var import_dotenv2 = __toESM(require("dotenv"));
 var import_v318 = require("zod/v3");
+init_sdkErrors();
 import_dotenv2.default.config();
 var EvaluationSchema = import_v318.z.object({
   evaluation: import_v318.z.enum(["YES", "NO"]),
@@ -41073,9 +41295,14 @@ var V3Evaluator = class {
         screenshotDelayMs = 250,
         agentReasoning
       } = options;
-      if (!question) throw new Error("Question cannot be an empty string");
+      if (!question)
+        throw new StagehandInvalidArgumentError(
+          "Question cannot be an empty string"
+        );
       if (!answer && !screenshot)
-        throw new Error("Either answer (text) or screenshot must be provided");
+        throw new StagehandInvalidArgumentError(
+          "Either answer (text) or screenshot must be provided"
+        );
       if (Array.isArray(screenshot)) {
         return this._evaluateWithMultipleScreenshots({
           question,
@@ -41143,7 +41370,10 @@ ${agentReasoning}` : question
         systemPrompt = "You are an expert evaluator that returns YES or NO with a concise reasoning.",
         screenshotDelayMs = 250
       } = options;
-      if (!(questions == null ? void 0 : questions.length)) throw new Error("Questions array cannot be empty");
+      if (!(questions == null ? void 0 : questions.length))
+        throw new StagehandInvalidArgumentError(
+          "Questions array cannot be empty"
+        );
       yield new Promise((r) => setTimeout(r, screenshotDelayMs));
       let imageBuffer;
       if (screenshot) {
@@ -41214,9 +41444,14 @@ You will be given multiple questions${screenshot ? " with a screenshot" : ""}. $
         ${agentReasoning ? "The agent's reasoning provides crucial context about what actions were attempted, what was observed, and the decision-making process. Use this alongside the visual evidence to make a comprehensive evaluation." : ""}
         Today's date is ${(/* @__PURE__ */ new Date()).toLocaleDateString()}`
       } = options;
-      if (!question) throw new Error("Question cannot be an empty string");
+      if (!question)
+        throw new StagehandInvalidArgumentError(
+          "Question cannot be an empty string"
+        );
       if (!screenshots || screenshots.length === 0)
-        throw new Error("At least one screenshot must be provided");
+        throw new StagehandInvalidArgumentError(
+          "At least one screenshot must be provided"
+        );
       const llmClient = this.getClient();
       const imageContents = screenshots.map((s) => ({
         type: "image_url",
@@ -41270,9 +41505,12 @@ I'm providing ${screenshots.length} screenshots showing the progression of the t
   AnnotatedScreenshotText,
   BrowserbaseSessionNotFoundError,
   CaptchaTimeoutError,
+  ConnectionTimeoutError,
   ConsoleMessage,
   ContentFrameNotFoundError,
   CreateChatCompletionResponseError,
+  CuaModelRequiredError,
+  ElementNotVisibleError,
   ExperimentalApiConflictError,
   ExperimentalNotConfiguredError,
   HandlerNotInitializedError,
@@ -41283,7 +41521,10 @@ I'm providing ${screenshots.length} screenshots showing the progression of the t
   MCPConnectionError,
   MissingEnvironmentVariableError,
   MissingLLMConfigurationError,
+  PageNotFoundError,
   Response,
+  ResponseBodyError,
+  ResponseParseError,
   Stagehand,
   StagehandAPIError,
   StagehandAPIUnauthorizedError,
@@ -41306,6 +41547,7 @@ I'm providing ${screenshots.length} screenshots showing the progression of the t
   StagehandShadowRootMissingError,
   StagehandShadowSegmentEmptyError,
   StagehandShadowSegmentNotFoundError,
+  TimeoutError,
   UnsupportedAISDKModelProviderError,
   UnsupportedModelError,
   UnsupportedModelProviderError,