@browserbasehq/orca 3.0.0-preview.8 → 3.0.1

package/dist/index.js

@@ -603,6 +603,19 @@ function captureHybridSnapshot(page, options) {
     const perFrameMaps = /* @__PURE__ */ new Map();
     const requestedFocus = (_b = options == null ? void 0 : options.focusSelector) == null ? void 0 : _b.trim();
     if (requestedFocus) {
+      const logScopeFallback = () => {
+        var _a2;
+        v3Logger({
+          message: `Unable to narrow scope with selector. Falling back to using full DOM`,
+          level: 1,
+          auxiliary: {
+            arguments: {
+              value: `selector: ${(_a2 = options == null ? void 0 : options.focusSelector) == null ? void 0 : _a2.trim()}`,
+              type: "string"
+            }
+          }
+        });
+      };
       try {
         let targetFrameId;
         let tailSelector;
@@ -641,7 +654,7 @@ function captureHybridSnapshot(page, options) {
           /*attemptOwnerLookup=*/
           sameSessionAsParent
         );
-        const { outline, urlMap } = yield a11yForFrame(
+        const { outline, urlMap, scopeApplied } = yield a11yForFrame(
           owningSess,
           targetFrameId,
           {
@@ -663,7 +676,7 @@ function captureHybridSnapshot(page, options) {
           }
         }
         const combinedUrlMap2 = __spreadValues({}, urlMap);
-        return {
+        const snapshot = {
           combinedTree: outline,
           combinedXpathMap: combinedXpathMap2,
           combinedUrlMap: combinedUrlMap2,
@@ -676,7 +689,12 @@ function captureHybridSnapshot(page, options) {
             }
           ]
         };
+        if (scopeApplied) {
+          return snapshot;
+        }
+        logScopeFallback();
       } catch (e) {
+        logScopeFallback();
       }
     }
     function buildSessionDomIndex(session, pierce2) {
@@ -1144,6 +1162,7 @@ function a11yForFrame(session, frameId, opts) {
       const enc = opts.encode(be);
       urlMap[enc] = url;
     }
+    let scopeApplied = false;
     const nodesForOutline = yield (() => __async(null, null, function* () {
       var _a2, _b2, _c;
       const sel = (_a2 = opts.focusSelector) == null ? void 0 : _a2.trim();
@@ -1160,6 +1179,7 @@ function a11yForFrame(session, frameId, opts) {
         if (typeof be !== "number") return nodes;
         const target = nodes.find((n) => n.backendDOMNodeId === be);
         if (!target) return nodes;
+        scopeApplied = true;
         const keep = /* @__PURE__ */ new Set([target.nodeId]);
         const queue = [target];
         while (queue.length) {
@@ -1181,7 +1201,7 @@ function a11yForFrame(session, frameId, opts) {
     const decorated = decorateRoles(nodesForOutline, opts);
     const { tree } = yield buildHierarchicalTree(decorated, opts);
     const simplified = tree.map((n) => formatTreeLine(n)).join("\n");
-    return { outline: simplified.trimEnd(), urlMap };
+    return { outline: simplified.trimEnd(), urlMap, scopeApplied };
   });
 }
 function resolveObjectIdForXPath(session, xpath, frameId) {
@@ -1532,6 +1552,7 @@ var IFRAME_STEP_RE;
 var init_snapshot = __esm({
   "lib/v3/understudy/a11y/snapshot.ts"() {
     init_executionContextRegistry();
+    init_logger();
     IFRAME_STEP_RE = /^iframe(?:\[\d+])?$/i;
   }
 });
@@ -3908,11 +3929,11 @@ var require_src = __commonJS({
 var require_is_docker = __commonJS({
   "../../node_modules/.pnpm/is-docker@2.2.1/node_modules/is-docker/index.js"(exports2, module2) {
     "use strict";
-    var fs7 = require("fs");
+    var fs8 = require("fs");
     var isDocker;
     function hasDockerEnv() {
       try {
-        fs7.statSync("/.dockerenv");
+        fs8.statSync("/.dockerenv");
         return true;
       } catch (_) {
         return false;
@@ -3920,7 +3941,7 @@ var require_is_docker = __commonJS({
     }
     function hasDockerCGroup() {
       try {
-        return fs7.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
+        return fs8.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
       } catch (_) {
         return false;
       }
@@ -3939,7 +3960,7 @@ var require_is_wsl = __commonJS({
   "../../node_modules/.pnpm/is-wsl@2.2.0/node_modules/is-wsl/index.js"(exports2, module2) {
     "use strict";
     var os3 = require("os");
-    var fs7 = require("fs");
+    var fs8 = require("fs");
     var isDocker = require_is_docker();
     var isWsl3 = () => {
       if (process.platform !== "linux") {
@@ -3952,7 +3973,7 @@ var require_is_wsl = __commonJS({
         return true;
       }
       try {
-        return fs7.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft") ? !isDocker() : false;
+        return fs8.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft") ? !isDocker() : false;
       } catch (_) {
         return false;
       }
@@ -3965,6 +3986,342 @@ var require_is_wsl = __commonJS({
   }
 });
 
+// lib/v3/understudy/consoleMessage.ts
+function formatRemoteObject(obj) {
+  var _a;
+  if (!obj) return "";
+  if ("value" in obj) {
+    const value = obj.value;
+    if (value === void 0) return "";
+    if (typeof value === "string") return value;
+    try {
+      return JSON.stringify(value);
+    } catch (e) {
+      return String(value);
+    }
+  }
+  if (obj.unserializableValue) return obj.unserializableValue;
+  if (obj.description) return obj.description;
+  return (_a = obj.type) != null ? _a : "";
+}
+var ConsoleMessage;
+var init_consoleMessage = __esm({
+  "lib/v3/understudy/consoleMessage.ts"() {
+    ConsoleMessage = class {
+      constructor(event, pageRef) {
+        this.event = event;
+        this.pageRef = pageRef;
+      }
+      type() {
+        return this.event.type;
+      }
+      text() {
+        const args = this.args();
+        if (!args.length) return "";
+        return args.map((arg) => formatRemoteObject(arg)).filter((chunk) => chunk.length > 0).join(" ");
+      }
+      args() {
+        return this.event.args ? [...this.event.args] : [];
+      }
+      location() {
+        var _a, _b;
+        const frame = (_b = (_a = this.event.stackTrace) == null ? void 0 : _a.callFrames) == null ? void 0 : _b[0];
+        return {
+          url: frame == null ? void 0 : frame.url,
+          lineNumber: frame == null ? void 0 : frame.lineNumber,
+          columnNumber: frame == null ? void 0 : frame.columnNumber
+        };
+      }
+      page() {
+        return this.pageRef;
+      }
+      timestamp() {
+        return this.event.timestamp;
+      }
+      raw() {
+        return this.event;
+      }
+      toString() {
+        return this.text();
+      }
+    };
+  }
+});
+
+// lib/v3/understudy/response.ts
+function createDeferred() {
+  let resolve3;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve3 = res;
+    reject = rej;
+  });
+  return { promise, resolve: resolve3, reject };
+}
+function normaliseHeaderName(name) {
+  return name.toLowerCase();
+}
+function splitHeaderValues(value) {
+  return value.split(/\r?\n/).map((part) => part.trim()).filter(Boolean);
+}
+function parseHeadersText(headersText) {
+  if (!headersText) return [];
+  const lines = headersText.split(/\r?\n/);
+  const entries = [];
+  for (const line of lines) {
+    if (!line || line.startsWith("HTTP/")) continue;
+    const index = line.indexOf(":");
+    if (index === -1) continue;
+    const name = line.slice(0, index).trim();
+    const value = line.slice(index + 1).trim();
+    entries.push({ name, value });
+  }
+  return entries;
+}
+var Response;
+var init_response = __esm({
+  "lib/v3/understudy/response.ts"() {
+    Response = class {
+      /**
+       * Build a response wrapper from the CDP notification associated with a
+       * navigation. The constructor captures the owning page/session so follow-up
+       * methods (body/text/json) can query CDP on-demand. The `response` payload is
+       * the raw `Protocol.Network.Response` object emitted by Chrome.
+       */
+      constructor(params) {
+        this.headersArrayCache = null;
+        this.allHeadersCache = null;
+        this.headerValuesMap = /* @__PURE__ */ new Map();
+        this.finishedDeferred = createDeferred();
+        this.finishedSettled = false;
+        this.extraInfoHeaders = null;
+        var _a;
+        this.page = params.page;
+        this.session = params.session;
+        this.requestId = params.requestId;
+        this.frameId = params.frameId;
+        this.loaderId = params.loaderId;
+        this.response = params.response;
+        this.fromServiceWorkerFlag = params.fromServiceWorker;
+        if (params.response.remoteIPAddress && params.response.remotePort !== void 0) {
+          this.serverAddress = {
+            ipAddress: params.response.remoteIPAddress,
+            port: params.response.remotePort
+          };
+        } else {
+          this.serverAddress = null;
+        }
+        this.headersObject = {};
+        for (const [name, value] of Object.entries((_a = this.response.headers) != null ? _a : {})) {
+          const lower = normaliseHeaderName(name);
+          if (value === void 0) continue;
+          const values = splitHeaderValues(String(value));
+          this.headerValuesMap.set(lower, values);
+          this.headersObject[lower] = values.join(", ");
+        }
+      }
+      /** URL associated with the navigation request. */
+      url() {
+        return this.response.url;
+      }
+      /** HTTP status code reported by Chrome. */
+      status() {
+        return this.response.status;
+      }
+      /** Human-readable status text that accompanied the response. */
+      statusText() {
+        return this.response.statusText;
+      }
+      /** Convenience predicate that checks for 2xx statuses. */
+      ok() {
+        const status = this.status();
+        return status >= 200 && status <= 299;
+      }
+      /** Returns the Stagehand frame object that initiated the navigation. */
+      frame() {
+        if (!this.frameId) return null;
+        try {
+          return this.page.frameForId(this.frameId);
+        } catch (e) {
+          return null;
+        }
+      }
+      /** Indicates whether the response was serviced by a Service Worker. */
+      fromServiceWorker() {
+        return this.fromServiceWorkerFlag;
+      }
+      /**
+       * Returns TLS security metadata when provided by the browser. In practice
+       * this includes certificate issuer, protocol, and validity interval.
+       */
+      securityDetails() {
+        return __async(this, null, function* () {
+          var _a;
+          return (_a = this.response.securityDetails) != null ? _a : null;
+        });
+      }
+      /** Returns the resolved server address for the navigation when available. */
+      serverAddr() {
+        return __async(this, null, function* () {
+          var _a;
+          return (_a = this.serverAddress) != null ? _a : null;
+        });
+      }
+      /**
+       * Returns the response headers normalised to lowercase keys. Matches the
+       * behaviour of Playwright's `headers()` by eliding duplicate header entries.
+       */
+      headers() {
+        return __spreadValues({}, this.headersObject);
+      }
+      /**
+       * Returns all headers including those only surfaced through
+       * `responseReceivedExtraInfo` such as `set-cookie`. Values are reported as the
+       * browser sends them (no further splitting or concatenation).
+       */
+      allHeaders() {
+        return __async(this, null, function* () {
+          var _a, _b;
+          if (this.allHeadersCache) return __spreadValues({}, this.allHeadersCache);
+          const source = (_b = (_a = this.extraInfoHeaders) != null ? _a : this.response.headers) != null ? _b : {};
+          const map = {};
+          for (const [name, value] of Object.entries(source)) {
+            map[name] = String(value);
+          }
+          this.allHeadersCache = map;
+          return __spreadValues({}, map);
+        });
+      }
+      /** Returns a concatenated header string for the supplied header name. */
+      headerValue(name) {
+        return __async(this, null, function* () {
+          const values = yield this.headerValues(name);
+          if (!values.length) return null;
+          return values.join(", ");
+        });
+      }
+      /** Returns all values for a header (case-insensitive lookup). */
+      headerValues(name) {
+        return __async(this, null, function* () {
+          var _a;
+          const lower = normaliseHeaderName(name);
+          if (this.extraInfoHeaders) {
+            const raw = (_a = this.extraInfoHeaders[name]) != null ? _a : this.extraInfoHeaders[lower];
+            if (raw !== void 0) {
+              return splitHeaderValues(String(raw));
+            }
+          }
+          const values = this.headerValuesMap.get(lower);
+          return values ? [...values] : [];
+        });
+      }
+      /**
+       * Returns header entries preserving their original wire casing and ordering.
+       * Falls back to the CDP object when the raw header text is unavailable.
+       */
+      headersArray() {
+        return __async(this, null, function* () {
+          var _a, _b;
+          if (this.headersArrayCache) return [...this.headersArrayCache];
+          const entriesFromText = parseHeadersText(this.extraInfoHeadersText);
+          if (entriesFromText.length > 0) {
+            this.headersArrayCache = entriesFromText;
+            return [...entriesFromText];
+          }
+          const entries = [];
+          const source = (_b = (_a = this.extraInfoHeaders) != null ? _a : this.response.headers) != null ? _b : {};
+          for (const [name, value] of Object.entries(source)) {
+            const values = splitHeaderValues(String(value));
+            for (const val of values) {
+              entries.push({ name, value: val });
+            }
+          }
+          this.headersArrayCache = entries;
+          return [...entries];
+        });
+      }
+      /**
+       * Requests the raw response body from Chrome DevTools Protocol. The method is
+       * intentionally lazy because not every caller needs the payload, and CDP only
+       * allows retrieving it once the response completes.
+       */
+      body() {
+        return __async(this, null, function* () {
+          const result = yield this.session.send(
+            "Network.getResponseBody",
+            { requestId: this.requestId }
+          ).catch((error) => {
+            throw new Error(`Failed to retrieve response body: ${String(error)}`);
+          });
+          if (result.base64Encoded) {
+            return Buffer.from(result.body, "base64");
+          }
+          return Buffer.from(result.body, "utf-8");
+        });
+      }
+      /** Decodes the response body as UTF-8 text. */
+      text() {
+        return __async(this, null, function* () {
+          const buffer = yield this.body();
+          return buffer.toString("utf-8");
+        });
+      }
+      /** Parses the response body as JSON and throws if parsing fails. */
+      json() {
+        return __async(this, null, function* () {
+          const text = yield this.text();
+          try {
+            return JSON.parse(text);
+          } catch (error) {
+            throw new Error(`Failed to parse JSON response: ${String(error)}`);
+          }
+        });
+      }
+      /**
+       * Resolves once the underlying network request completes or fails. Mirrors
+       * Playwright's behaviour by resolving to `null` on success and to an `Error`
+       * instance when Chrome reports `Network.loadingFailed`.
+       */
+      finished() {
+        return __async(this, null, function* () {
+          return this.finishedDeferred.promise;
+        });
+      }
+      /**
+       * Internal helper invoked by the navigation tracker when CDP reports extra
+       * header information. This keeps the cached header views in sync with the
+       * richer metadata.
+       */
+      applyExtraInfo(event) {
+        var _a;
+        this.extraInfoHeaders = event.headers;
+        this.extraInfoHeadersText = event.headersText;
+        this.allHeadersCache = null;
+        this.headersArrayCache = null;
+        this.headersObject = {};
+        this.headerValuesMap.clear();
+        const source = (_a = event.headers) != null ? _a : {};
+        for (const [name, value] of Object.entries(source)) {
+          const lower = normaliseHeaderName(name);
+          const segments = splitHeaderValues(String(value));
+          this.headerValuesMap.set(lower, segments);
+          this.headersObject[lower] = segments.join(", ");
+        }
+      }
+      /** Marks the response as finished and resolves the `finished()` promise. */
+      markFinished(error) {
+        if (this.finishedSettled) return;
+        this.finishedSettled = true;
+        if (error) {
+          this.finishedDeferred.resolve(error);
+        } else {
+          this.finishedDeferred.resolve(null);
+        }
+      }
+    };
+  }
+});
+
 // lib/v3/understudy/frame.ts
 var Frame;
 var init_frame = __esm({
@@ -4084,12 +4441,32 @@ var init_frame = __esm({
       /** Page.captureScreenshot (frame-scoped session) */
       screenshot(options) {
         return __async(this, null, function* () {
+          var _a;
           yield this.session.send("Page.enable");
+          const format = (_a = options == null ? void 0 : options.type) != null ? _a : "png";
           const params = {
-            format: "png",
+            format,
+            fromSurface: true,
             captureBeyondViewport: options == null ? void 0 : options.fullPage
           };
-          if (options == null ? void 0 : options.clip) params.clip = __spreadProps(__spreadValues({}, options.clip), { scale: 1 });
+          const clampScale = (value) => Math.min(2, Math.max(0.1, value));
+          const normalizedScale = typeof (options == null ? void 0 : options.scale) === "number" ? clampScale(options.scale) : void 0;
+          if (options == null ? void 0 : options.clip) {
+            const clip = {
+              x: options.clip.x,
+              y: options.clip.y,
+              width: options.clip.width,
+              height: options.clip.height,
+              scale: normalizedScale != null ? normalizedScale : 1
+            };
+            params.clip = clip;
+          } else if (normalizedScale !== void 0 && normalizedScale !== 1) {
+            params.scale = normalizedScale;
+          }
+          if (format === "jpeg" && typeof (options == null ? void 0 : options.quality) === "number") {
+            const q = Math.round(options.quality);
+            params.quality = Math.min(100, Math.max(0, q));
+          }
           const { data } = yield this.session.send(
             "Page.captureScreenshot",
             params
@@ -4925,14 +5302,529 @@ var init_lifecycleWatcher = __esm({
   }
 });
 
+// lib/v3/understudy/navigationResponseTracker.ts
+var NavigationResponseTracker;
+var init_navigationResponseTracker = __esm({
+  "lib/v3/understudy/navigationResponseTracker.ts"() {
+    init_response();
+    NavigationResponseTracker = class {
+      /**
+       * Create a tracker bound to a specific navigation command. The tracker begins
+       * listening for network events immediately so it should be constructed before
+       * the navigation request is dispatched.
+       */
+      constructor(params) {
+        this.selectedRequestId = null;
+        this.selectedResponse = null;
+        this.acceptNextWithoutLoader = false;
+        this.responseResolved = false;
+        this.pendingResponsesByLoader = /* @__PURE__ */ new Map();
+        this.pendingExtraInfo = /* @__PURE__ */ new Map();
+        this.listeners = [];
+        this.page = params.page;
+        this.session = params.session;
+        this.navigationCommandId = params.navigationCommandId;
+        this.responsePromise = new Promise((resolve3) => {
+          this.resolveResponse = (value) => {
+            if (this.responseResolved) return;
+            this.responseResolved = true;
+            resolve3(value);
+          };
+        });
+        this.installListeners();
+      }
+      /** Stop listening for CDP events and release any pending bookkeeping. */
+      dispose() {
+        for (const { event, handler } of this.listeners) {
+          this.session.off(event, handler);
+        }
+        this.listeners.length = 0;
+        this.pendingResponsesByLoader.clear();
+        this.pendingExtraInfo.clear();
+      }
+      /**
+       * Hint the tracker with the loader id returned by `Page.navigate`. Chrome only
+       * emits this once the browser begins navigating, so we store early responses
+       * and match them once the loader id is known.
+       */
+      setExpectedLoaderId(loaderId) {
+        if (!loaderId) return;
+        this.expectedLoaderId = loaderId;
+        const pending = this.pendingResponsesByLoader.get(loaderId);
+        if (pending) {
+          this.pendingResponsesByLoader.delete(loaderId);
+          this.selectResponse(pending);
+        }
+      }
+      /**
+       * Some navigation APIs (reload/history traversal) do not provide a loader id
+       * up front. This flag instructs the tracker to accept the next qualifying
+       * document response even if no loader id has been announced yet.
+       */
+      expectNavigationWithoutKnownLoader() {
+        this.acceptNextWithoutLoader = true;
+      }
+      /**
+       * Returns a promise that resolves with the matched response (or `null` when
+       * no document response was observed).
+       */
+      navigationCompleted() {
+        return __async(this, null, function* () {
+          if (!this.responseResolved) {
+            queueMicrotask(() => {
+              if (!this.responseResolved) this.resolveResponse(null);
+            });
+          }
+          return this.responsePromise;
+        });
+      }
+      /** Expose the raw response promise (mainly for tests). */
+      response() {
+        return __async(this, null, function* () {
+          return this.responsePromise;
+        });
+      }
+      /** Register all CDP listeners relevant to navigation tracking. */
+      installListeners() {
+        this.addListener("Network.responseReceived", (event) => {
+          this.onResponseReceived(event);
+        });
+        this.addListener("Network.responseReceivedExtraInfo", (event) => {
+          this.onResponseReceivedExtraInfo(
+            event
+          );
+        });
+        this.addListener("Network.loadingFinished", (event) => {
+          this.onLoadingFinished(event);
+        });
+        this.addListener("Network.loadingFailed", (event) => {
+          this.onLoadingFailed(event);
+        });
+      }
+      /** Attach a CDP listener and track it for later disposal. */
+      addListener(event, handler) {
+        this.session.on(event, handler);
+        this.listeners.push({ event, handler });
+      }
+      /** Handle the initial response payload for document navigations. */
+      onResponseReceived(event) {
+        var _a;
+        if (!this.page.isCurrentNavigationCommand(this.navigationCommandId)) return;
+        if (!event || !event.response) return;
+        if (event.type !== "Document") return;
+        if (event.frameId !== this.page.mainFrameId()) return;
+        const loaderId = (_a = event.loaderId) != null ? _a : "";
+        if (this.acceptNextWithoutLoader) {
+          this.acceptNextWithoutLoader = false;
+          this.selectResponse(event);
+          return;
+        }
+        if (this.expectedLoaderId) {
+          if (loaderId && loaderId !== this.expectedLoaderId) {
+            this.pendingResponsesByLoader.set(loaderId, event);
+            return;
+          }
+          this.selectResponse(event);
+          return;
+        }
+        if (loaderId) {
+          this.pendingResponsesByLoader.set(loaderId, event);
+          return;
+        }
+        this.selectResponse(event);
+      }
+      /** Merge auxiliary header information once Chrome exposes it. */
+      onResponseReceivedExtraInfo(event) {
+        var _a;
+        if (!event || !event.requestId) return;
+        if (this.selectedRequestId && event.requestId === this.selectedRequestId) {
+          (_a = this.selectedResponse) == null ? void 0 : _a.applyExtraInfo(event);
+          return;
+        }
+        this.pendingExtraInfo.set(event.requestId, event);
+      }
+      /** Resolve the response's finished promise when the request completes. */
+      onLoadingFinished(event) {
+        var _a;
+        if (!event || !event.requestId) return;
+        if (event.requestId !== this.selectedRequestId) return;
+        (_a = this.selectedResponse) == null ? void 0 : _a.markFinished(null);
+      }
+      /** Resolve the response's finished promise with an error on failure. */
+      onLoadingFailed(event) {
+        var _a;
+        if (!event || !event.requestId) return;
+        if (event.requestId !== this.selectedRequestId) return;
+        const errorText = event.errorText || "Navigation request failed";
+        (_a = this.selectedResponse) == null ? void 0 : _a.markFinished(new Error(errorText));
+      }
+      /**
+       * Create the `Response` wrapper for the chosen document response and
+       * resolve awaiting consumers. Subsequent events flesh out the header/body
+       * helpers and mark the request as finished.
+       */
+      selectResponse(event) {
+        var _a, _b, _c, _d, _e, _f;
+        if (event.loaderId) {
+          this.pendingResponsesByLoader.delete(event.loaderId);
+        }
+        if (this.responseResolved) return;
+        if (this.selectedResponse) return;
+        const protocol = (_c = (_b = (_a = event.response) == null ? void 0 : _a.protocol) == null ? void 0 : _b.toLowerCase()) != null ? _c : "";
+        const url = (_e = (_d = event.response) == null ? void 0 : _d.url) != null ? _e : "";
+        const isDataUrl = protocol === "data" || url.startsWith("data:");
+        const isAboutUrl = protocol === "about" || url.startsWith("about:");
+        if (isDataUrl || isAboutUrl) {
+          this.pendingExtraInfo.delete(event.requestId);
+          this.selectedRequestId = null;
+          this.selectedResponse = null;
+          this.resolveResponse(null);
+          return;
+        }
+        const response = new Response({
+          page: this.page,
+          session: this.session,
+          requestId: event.requestId,
+          frameId: event.frameId,
+          loaderId: event.loaderId,
+          response: event.response,
+          fromServiceWorker: Boolean((_f = event.response) == null ? void 0 : _f.fromServiceWorker)
+        });
+        this.selectedRequestId = event.requestId;
+        this.selectedResponse = response;
+        const extraInfo = this.pendingExtraInfo.get(event.requestId);
+        if (extraInfo) {
+          response.applyExtraInfo(extraInfo);
+          this.pendingExtraInfo.delete(event.requestId);
+        }
+        this.resolveResponse(response);
+      }
+    };
+  }
+});
+
+// lib/v3/understudy/screenshotUtils.ts
+function collectFramesForScreenshot(page) {
+  const seen = /* @__PURE__ */ new Map();
+  const main = page.mainFrame();
+  seen.set(main.frameId, main);
+  for (const frame of page.frames()) {
+    seen.set(frame.frameId, frame);
+  }
+  return Array.from(seen.values());
+}
+function normalizeScreenshotClip(clip) {
+  const x = Number(clip.x);
+  const y = Number(clip.y);
+  const width = Number(clip.width);
+  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`);
+    }
+  }
+  if (width <= 0 || height <= 0) {
+    throw new Error("screenshot: clip width/height must be positive");
+  }
+  return { x, y, width, height };
+}
+function computeScreenshotScale(page, mode) {
+  return __async(this, null, function* () {
+    if (mode !== "css") return void 0;
+    try {
+      const frame = page.mainFrame();
+      const dpr = yield frame.evaluate(() => {
+        const ratio = Number(window.devicePixelRatio || 1);
+        return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+      }).catch(() => 1);
+      const safeRatio = Number.isFinite(dpr) && dpr > 0 ? dpr : 1;
+      return Math.min(2, Math.max(0.1, 1 / safeRatio));
+    } catch (e) {
+      return 1;
+    }
+  });
+}
+function setTransparentBackground(session) {
+  return __async(this, null, function* () {
+    yield session.send("Emulation.setDefaultBackgroundColorOverride", {
+      color: { r: 0, g: 0, b: 0, a: 0 }
+    }).catch(() => {
+    });
+    return () => __async(null, null, function* () {
+      yield session.send("Emulation.setDefaultBackgroundColorOverride", {}).catch(() => {
+      });
+    });
+  });
+}
+function applyStyleToFrames(frames, css, label) {
+  return __async(this, null, function* () {
+    const trimmed = css.trim();
+    if (!trimmed) return () => __async(null, null, function* () {
+    });
+    const token = `__v3_style_${label}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    yield Promise.all(
+      frames.map(
+        (frame) => frame.evaluate(
+          ({ css: css2, token: token2 }) => {
+            try {
+              const doc = document;
+              if (!doc) return;
+              const style = doc.createElement("style");
+              style.setAttribute("data-stagehand-style", token2);
+              style.textContent = css2;
+              const parent = doc.head || doc.documentElement || doc.body;
+              parent == null ? void 0 : parent.appendChild(style);
+            } catch (e) {
+            }
+          },
+          { css: trimmed, token }
+        ).catch(() => {
+        })
+      )
+    );
+    return () => __async(null, null, function* () {
+      yield Promise.all(
+        frames.map(
+          (frame) => frame.evaluate((token2) => {
+            try {
+              const doc = document;
+              if (!doc) return;
+              const nodes = doc.querySelectorAll(
+                `[data-stagehand-style="${token2}"]`
+              );
+              nodes.forEach((node) => node.remove());
+            } catch (e) {
+            }
+          }, token).catch(() => {
+          })
+        )
+      );
+    });
+  });
+}
+function disableAnimations(frames) {
+  return __async(this, null, function* () {
+    const css = `
+*,
+*::before,
+*::after {
+  animation-delay: 0s !important;
+  animation-duration: 0s !important;
+  animation-iteration-count: 1 !important;
+  animation-play-state: paused !important;
+  transition-property: none !important;
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+}`;
+    const cleanup = yield applyStyleToFrames(frames, css, "animations");
+    yield Promise.all(
+      frames.map(
+        (frame) => frame.evaluate(() => {
+          var _a, _b, _c, _d, _e;
+          try {
+            const animations = typeof document.getAnimations === "function" ? document.getAnimations() : [];
+            for (const animation of animations) {
+              try {
+                const details = (_b = (_a = animation.effect) == null ? void 0 : _a.getComputedTiming) == null ? void 0 : _b.call(_a);
+                if (details && details.iterations !== Infinity) {
+                  (_c = animation.finish) == null ? void 0 : _c.call(animation);
+                } else {
+                  (_d = animation.cancel) == null ? void 0 : _d.call(animation);
+                }
+              } catch (e) {
+                (_e = animation.cancel) == null ? void 0 : _e.call(animation);
+              }
+            }
+          } catch (e) {
+          }
+        }).catch(() => {
+        })
+      )
+    );
+    return cleanup;
+  });
+}
+function hideCaret(frames) {
+  return __async(this, null, function* () {
+    const css = `
+input,
+textarea,
+[contenteditable],
+[contenteditable=""],
+[contenteditable="true"],
+[contenteditable="plaintext-only"],
+*:focus {
+  caret-color: transparent !important;
+}`;
+    return applyStyleToFrames(frames, css, "caret");
+  });
+}
+function applyMaskOverlays(locators, color) {
+  return __async(this, null, function* () {
+    var _a;
+    const rectsByFrame = /* @__PURE__ */ new Map();
+    for (const locator of locators) {
+      try {
+        const info = yield resolveMaskRect(locator);
+        if (!info) continue;
+        const list = (_a = rectsByFrame.get(info.frame)) != null ? _a : [];
+        list.push(info.rect);
+        rectsByFrame.set(info.frame, list);
+      } catch (e) {
+      }
+    }
+    if (rectsByFrame.size === 0) {
+      return () => __async(null, null, function* () {
+      });
+    }
+    const token = `__v3_mask_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    yield Promise.all(
+      Array.from(rectsByFrame.entries()).map(
+        ([frame, rects]) => frame.evaluate(
+          ({ rects: rects2, color: color2, token: token2 }) => {
+            try {
+              const doc = document;
+              if (!doc) return;
+              const root = doc.documentElement || doc.body;
+              if (!root) return;
+              for (const rect of rects2) {
+                const el = doc.createElement("div");
+                el.setAttribute("data-stagehand-mask", token2);
+                el.style.position = "absolute";
+                el.style.left = `${rect.x}px`;
+                el.style.top = `${rect.y}px`;
+                el.style.width = `${rect.width}px`;
+                el.style.height = `${rect.height}px`;
+                el.style.backgroundColor = color2;
+                el.style.pointerEvents = "none";
+                el.style.zIndex = "2147483647";
+                el.style.opacity = "1";
+                el.style.mixBlendMode = "normal";
+                root.appendChild(el);
+              }
+            } catch (e) {
+            }
+          },
+          { rects, color, token }
+        ).catch(() => {
+        })
+      )
+    );
+    return () => __async(null, null, function* () {
+      yield Promise.all(
+        Array.from(rectsByFrame.keys()).map(
+          (frame) => frame.evaluate((token2) => {
+            try {
+              const doc = document;
+              if (!doc) return;
+              const nodes = doc.querySelectorAll(
+                `[data-stagehand-mask="${token2}"]`
+              );
+              nodes.forEach((node) => node.remove());
+            } catch (e) {
+            }
+          }, token).catch(() => {
+          })
+        )
+      );
+    });
+  });
+}
+function resolveMaskRect(locator) {
+  return __async(this, null, function* () {
+    const frame = locator.getFrame();
+    const session = frame.session;
+    let objectId = null;
+    try {
+      const resolved = yield locator.resolveNode();
+      objectId = resolved.objectId;
+      const result = yield session.send(
+        "Runtime.callFunctionOn",
+        {
+          objectId,
+          functionDeclaration: `function() {
+          if (!this || typeof this.getBoundingClientRect !== 'function') return null;
+          const rect = this.getBoundingClientRect();
+          if (!rect) return null;
+          const style = window.getComputedStyle(this);
+          if (!style) return null;
+          if (style.visibility === 'hidden' || style.display === 'none') return null;
+          if (rect.width <= 0 || rect.height <= 0) return null;
+          return {
+            x: rect.left + window.scrollX,
+            y: rect.top + window.scrollY,
+            width: rect.width,
+            height: rect.height,
+          };
+        }`,
+          returnByValue: true
+        }
+      );
+      if (result.exceptionDetails) {
+        return null;
+      }
+      const rect = result.result.value;
+      if (!rect) return null;
+      const { x, y, width, height } = rect;
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+        return null;
+      }
+      return { frame, rect: { x, y, width, height } };
+    } catch (e) {
+      return null;
+    } finally {
+      if (objectId) {
+        yield session.send("Runtime.releaseObject", { objectId }).catch(() => {
+        });
+      }
+    }
+  });
+}
+function runScreenshotCleanups(cleanups) {
+  return __async(this, null, function* () {
+    for (let i = cleanups.length - 1; i >= 0; i -= 1) {
+      const fn = cleanups[i];
+      if (!fn) continue;
+      try {
+        const result = fn();
+        if (result && typeof result.then === "function") {
+          yield result;
+        }
+      } catch (e) {
+      }
+    }
+  });
+}
+function withScreenshotTimeout(timeoutMs, task) {
+  return __async(this, null, function* () {
+    if (!timeoutMs || timeoutMs <= 0) return task();
+    let timer = null;
+    const timeoutPromise = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(`screenshot: timeout of ${timeoutMs}ms exceeded`));
+      }, timeoutMs);
+    });
+    try {
+      return yield Promise.race([task(), timeoutPromise]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  });
+}
+var init_screenshotUtils = __esm({
+  "lib/v3/understudy/screenshotUtils.ts"() {
+  }
+});
+
 // lib/v3/understudy/page.ts
 var page_exports = {};
 __export(page_exports, {
   Page: () => Page
 });
-var LIFECYCLE_NAME, Page;
+var import_fs5, LIFECYCLE_NAME, Page;
 var init_page = __esm({
   "lib/v3/understudy/page.ts"() {
+    import_fs5 = require("fs");
     init_logger();
     init_frame();
     init_frameLocator();
@@ -4941,6 +5833,9 @@ var init_page = __esm({
     init_frameRegistry();
     init_networkManager();
     init_lifecycleWatcher();
+    init_navigationResponseTracker();
+    init_consoleMessage();
+    init_screenshotUtils();
     LIFECYCLE_NAME = {
       load: "load",
       domcontentloaded: "DOMContentLoaded",
@@ -4964,6 +5859,8 @@ var init_page = __esm({
         this.latestNavigationCommandId = 0;
         /** Optional API client for routing page operations to the API */
         this.apiClient = null;
+        this.consoleListeners = /* @__PURE__ */ new Set();
+        this.consoleHandlers = /* @__PURE__ */ new Map();
         // --- Optional visual cursor overlay management ---
         this.cursorEnabled = false;
         // Track pressed modifier keys
@@ -5165,6 +6062,9 @@ var init_page = __esm({
         var _a;
         if (childSession.id) this.sessions.set(childSession.id, childSession);
         this.networkManager.trackSession(childSession);
+        if (this.consoleListeners.size > 0) {
+          this.installConsoleTap(childSession);
+        }
         this.registry.adoptChildSession(
           (_a = childSession.id) != null ? _a : "child",
           childMainFrameId
@@ -5218,6 +6118,7 @@ var init_page = __esm({
           this.registry.onFrameDetached(fid, "remove");
           this.frameCache.delete(fid);
         }
+        this.teardownConsoleTap(sessionId);
         this.sessions.delete(sessionId);
         this.networkManager.untrackSession(sessionId);
       }
@@ -5248,10 +6149,65 @@ var init_page = __esm({
       unregisterSessionForNetwork(sessionId) {
         this.networkManager.untrackSession(sessionId);
       }
+      on(event, listener) {
+        if (event !== "console") {
+          throw new Error(`Unsupported event: ${event}`);
+        }
+        const firstListener = this.consoleListeners.size === 0;
+        this.consoleListeners.add(listener);
+        if (firstListener) {
+          this.ensureConsoleTaps();
+        }
+        return this;
+      }
+      once(event, listener) {
+        if (event !== "console") {
+          throw new Error(`Unsupported event: ${event}`);
+        }
+        const wrapper = (message) => {
+          this.off("console", wrapper);
+          listener(message);
+        };
+        return this.on("console", wrapper);
+      }
+      off(event, listener) {
+        if (event !== "console") {
+          throw new Error(`Unsupported event: ${event}`);
+        }
+        this.consoleListeners.delete(listener);
+        if (this.consoleListeners.size === 0) {
+          this.removeAllConsoleTaps();
+        }
+        return this;
+      }
       // ---------------- MAIN APIs ----------------
       targetId() {
         return this._targetId;
       }
+      /**
+       * Send a CDP command through the main session.
+       * Allows external consumers to execute arbitrary Chrome DevTools Protocol commands.
+       *
+       * @param method - The CDP method name (e.g., "Page.enable", "Runtime.evaluate")
+       * @param params - Optional parameters for the CDP command
+       * @returns Promise resolving to the typed CDP response
+       *
+       * @example
+       * // Enable the Runtime domain
+       * await page.sendCDP("Runtime.enable");
+       *
+       * @example
+       * // Evaluate JavaScript with typed response
+       * const result = await page.sendCDP<Protocol.Runtime.EvaluateResponse>(
+       *   "Runtime.evaluate",
+       *   { expression: "1 + 1" }
+       * );
+       */
+      sendCDP(method, params) {
+        return __async(this, null, function* () {
+          return this.mainSession.send(method, params);
+        });
+      }
       /** Seed the cached URL before navigation events converge. */
       seedCurrentUrl(url) {
         if (!url) return;
@@ -5290,6 +6246,8 @@ var init_page = __esm({
             yield new Promise((r) => setTimeout(r, 25));
           }
           this.networkManager.dispose();
+          this.removeAllConsoleTaps();
+          this.consoleListeners.clear();
         });
       }
       getFullFrameTree() {
@@ -5312,6 +6270,71 @@ var init_page = __esm({
       listAllFrameIds() {
         return this.registry.listAllFrames();
       }
+      ensureConsoleTaps() {
+        if (this.consoleListeners.size === 0) return;
+        this.installConsoleTap(this.mainSession);
+        for (const session of this.sessions.values()) {
+          this.installConsoleTap(session);
+        }
+      }
+      installConsoleTap(session) {
+        const key = this.sessionKey(session);
+        if (this.consoleHandlers.has(key)) return;
+        void session.send("Runtime.enable").catch(() => {
+        });
+        const handler = (evt) => {
+          this.emitConsole(evt);
+        };
+        session.on(
+          "Runtime.consoleAPICalled",
+          handler
+        );
+        this.consoleHandlers.set(key, handler);
+      }
+      sessionKey(session) {
+        var _a;
+        return (_a = session.id) != null ? _a : "__root__";
+      }
+      resolveSessionByKey(key) {
+        if (this.mainSession.id) {
+          if (this.mainSession.id === key) return this.mainSession;
+        } else if (key === "__root__") {
+          return this.mainSession;
+        }
+        return this.sessions.get(key);
+      }
+      teardownConsoleTap(key) {
+        const handler = this.consoleHandlers.get(key);
+        if (!handler) return;
+        const session = this.resolveSessionByKey(key);
+        session == null ? void 0 : session.off("Runtime.consoleAPICalled", handler);
+        this.consoleHandlers.delete(key);
+      }
+      removeAllConsoleTaps() {
+        for (const key of [...this.consoleHandlers.keys()]) {
+          this.teardownConsoleTap(key);
+        }
+      }
+      emitConsole(evt) {
+        if (this.consoleListeners.size === 0) return;
+        const message = new ConsoleMessage(evt, this);
+        const listeners = [...this.consoleListeners];
+        for (const listener of listeners) {
+          try {
+            listener(message);
+          } catch (error) {
+            v3Logger({
+              category: "page",
+              message: "Console listener threw",
+              level: 2,
+              auxiliary: {
+                error: { value: String(error), type: "string" },
+                type: { value: evt.type, type: "string" }
+              }
+            });
+          }
+        }
+      }
       // -------- Convenience APIs delegated to the current main frame --------
       /**
        * Navigate the page; optionally wait for a lifecycle state.
@@ -5323,6 +6346,11 @@ var init_page = __esm({
           const waitUntil = (_a = options == null ? void 0 : options.waitUntil) != null ? _a : "domcontentloaded";
           const timeout = (_b = options == null ? void 0 : options.timeoutMs) != null ? _b : 15e3;
           const navigationCommandId = this.beginNavigationCommand();
+          const tracker = new NavigationResponseTracker({
+            page: this,
+            session: this.mainSession,
+            navigationCommandId
+          });
           const watcher = new LifecycleWatcher({
             page: this,
             mainSession: this.mainSession,
@@ -5339,17 +6367,22 @@ var init_page = __esm({
                 this.mainFrameId()
               );
               this._currentUrl = url;
-              return;
+              return null;
             }
             const response = yield this.mainSession.send(
               "Page.navigate",
               { url }
             );
             this._currentUrl = url;
-            if (response == null ? void 0 : response.loaderId) watcher.setExpectedLoaderId(response.loaderId);
+            if (response == null ? void 0 : response.loaderId) {
+              watcher.setExpectedLoaderId(response.loaderId);
+              tracker.setExpectedLoaderId(response.loaderId);
+            }
             yield watcher.wait();
+            return yield tracker.navigationCompleted();
           } finally {
             watcher.dispose();
+            tracker.dispose();
           }
         });
       }
@@ -5362,6 +6395,12 @@ var init_page = __esm({
           const waitUntil = options == null ? void 0 : options.waitUntil;
           const timeout = (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 15e3;
           const navigationCommandId = this.beginNavigationCommand();
+          const tracker = new NavigationResponseTracker({
+            page: this,
+            session: this.mainSession,
+            navigationCommandId
+          });
+          tracker.expectNavigationWithoutKnownLoader();
           const watcher = waitUntil ? new LifecycleWatcher({
             page: this,
             mainSession: this.mainSession,
@@ -5377,8 +6416,10 @@ var init_page = __esm({
             if (watcher) {
               yield watcher.wait();
             }
+            return yield tracker.navigationCompleted();
           } finally {
             watcher == null ? void 0 : watcher.dispose();
+            tracker.dispose();
           }
         });
       }
@@ -5392,10 +6433,16 @@ var init_page = __esm({
             "Page.getNavigationHistory"
           );
           const prev = entries[currentIndex - 1];
-          if (!prev) return;
+          if (!prev) return null;
           const waitUntil = options == null ? void 0 : options.waitUntil;
           const timeout = (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 15e3;
           const navigationCommandId = this.beginNavigationCommand();
+          const tracker = new NavigationResponseTracker({
+            page: this,
+            session: this.mainSession,
+            navigationCommandId
+          });
+          tracker.expectNavigationWithoutKnownLoader();
           const watcher = waitUntil ? new LifecycleWatcher({
             page: this,
             mainSession: this.mainSession,
@@ -5412,8 +6459,10 @@ var init_page = __esm({
             if (watcher) {
               yield watcher.wait();
             }
+            return yield tracker.navigationCompleted();
           } finally {
             watcher == null ? void 0 : watcher.dispose();
+            tracker.dispose();
           }
         });
       }
@@ -5427,10 +6476,16 @@ var init_page = __esm({
             "Page.getNavigationHistory"
           );
           const next = entries[currentIndex + 1];
-          if (!next) return;
+          if (!next) return null;
           const waitUntil = options == null ? void 0 : options.waitUntil;
           const timeout = (_a = options == null ? void 0 : options.timeoutMs) != null ? _a : 15e3;
           const navigationCommandId = this.beginNavigationCommand();
+          const tracker = new NavigationResponseTracker({
+            page: this,
+            session: this.mainSession,
+            navigationCommandId
+          });
+          tracker.expectNavigationWithoutKnownLoader();
           const watcher = waitUntil ? new LifecycleWatcher({
             page: this,
             mainSession: this.mainSession,
@@ -5447,8 +6502,10 @@ var init_page = __esm({
             if (watcher) {
               yield watcher.wait();
             }
+            return yield tracker.navigationCompleted();
           } finally {
             watcher == null ? void 0 : watcher.dispose();
+            tracker.dispose();
           }
         });
       }
@@ -5500,11 +6557,99 @@ var init_page = __esm({
         });
       }
       /**
-       * Capture a screenshot (delegated to the current main frame).
+       * Capture a screenshot with Playwright-style options.
+       *
+       * @param options Optional screenshot configuration.
+       * @param options.animations Control CSS/Web animations during capture. Use
+       * "disabled" to fast-forward finite animations and pause infinite ones.
+       * @param options.caret Either hide the text caret (default) or leave it
+       * visible via "initial".
+       * @param options.clip Restrict capture to a specific rectangle (in CSS
+       * pixels). Cannot be combined with `fullPage`.
+       * @param options.fullPage Capture the full scrollable page instead of the
+       * current viewport.
+       * @param options.mask Array of locators that should be covered with an
+       * overlay while the screenshot is taken.
+       * @param options.maskColor CSS color used for the mask overlay (default
+       * `#FF00FF`).
+       * @param options.omitBackground Make the default page background transparent
+       * (PNG only).
+       * @param options.path File path to write the screenshot to. The file extension
+       * determines the image type when `type` is not explicitly provided.
+       * @param options.quality JPEG quality (0–100). Only applies when
+       * `type === "jpeg"`.
+       * @param options.scale Render scale: use "css" for one pixel per CSS pixel,
+       * otherwise the default "device" leverages the current device pixel ratio.
+       * @param options.style Additional CSS text injected into every frame before
+       * capture (removed afterwards).
+       * @param options.timeout Maximum capture duration in milliseconds before a
+       * timeout error is thrown.
+       * @param options.type Image format (`"png"` by default).
        */
       screenshot(options) {
         return __async(this, null, function* () {
-          return this.mainFrameWrapper.screenshot(options);
+          var _a, _b, _c, _d, _e;
+          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}"`);
+          }
+          if (opts.fullPage && opts.clip) {
+            throw new Error("screenshot: clip and fullPage cannot be used together");
+          }
+          if (type === "png" && typeof opts.quality === "number") {
+            throw new Error(
+              'screenshot: quality option is only valid for type="jpeg"'
+            );
+          }
+          const caretMode = (_b = opts.caret) != null ? _b : "hide";
+          const animationsMode = (_c = opts.animations) != null ? _c : "allow";
+          const scaleMode = (_d = opts.scale) != null ? _d : "device";
+          const frames = collectFramesForScreenshot(this);
+          const clip = opts.clip ? normalizeScreenshotClip(opts.clip) : void 0;
+          const captureScale = yield computeScreenshotScale(this, scaleMode);
+          const maskLocators = ((_e = opts.mask) != null ? _e : []).filter(
+            (locator) => Boolean(locator)
+          );
+          const cleanupTasks = [];
+          const exec = () => __async(this, null, function* () {
+            var _a2;
+            try {
+              if (opts.omitBackground) {
+                cleanupTasks.push(yield setTransparentBackground(this.mainSession));
+              }
+              if (animationsMode === "disabled") {
+                cleanupTasks.push(yield disableAnimations(frames));
+              }
+              if (caretMode === "hide") {
+                cleanupTasks.push(yield hideCaret(frames));
+              }
+              if (opts.style && opts.style.trim()) {
+                cleanupTasks.push(
+                  yield applyStyleToFrames(frames, opts.style, "custom")
+                );
+              }
+              if (maskLocators.length > 0) {
+                cleanupTasks.push(
+                  yield applyMaskOverlays(maskLocators, (_a2 = opts.maskColor) != null ? _a2 : "#FF00FF")
+                );
+              }
+              const buffer = yield this.mainFrameWrapper.screenshot({
+                fullPage: opts.fullPage,
+                clip,
+                type,
+                quality: type === "jpeg" ? opts.quality : void 0,
+                scale: captureScale
+              });
+              if (opts.path) {
+                yield import_fs5.promises.writeFile(opts.path, buffer);
+              }
+              return buffer;
+            } finally {
+              yield runScreenshotCleanups(cleanupTasks);
+            }
+          });
+          return withScreenshotTimeout(opts.timeout, exec);
         });
       }
       /**
@@ -6222,12 +7367,14 @@ var init_page = __esm({
 // lib/v3/index.ts
 var v3_exports = {};
 __export(v3_exports, {
+  AISdkClient: () => AISdkClient2,
   AVAILABLE_CUA_MODELS: () => AVAILABLE_CUA_MODELS,
   AgentProvider: () => AgentProvider,
   AgentScreenshotProviderError: () => AgentScreenshotProviderError,
   AnnotatedScreenshotText: () => AnnotatedScreenshotText,
   BrowserbaseSessionNotFoundError: () => BrowserbaseSessionNotFoundError,
   CaptchaTimeoutError: () => CaptchaTimeoutError,
+  ConsoleMessage: () => ConsoleMessage,
   ContentFrameNotFoundError: () => ContentFrameNotFoundError,
   CreateChatCompletionResponseError: () => CreateChatCompletionResponseError,
   ExperimentalApiConflictError: () => ExperimentalApiConflictError,
@@ -6240,6 +7387,7 @@ __export(v3_exports, {
   MCPConnectionError: () => MCPConnectionError,
   MissingEnvironmentVariableError: () => MissingEnvironmentVariableError,
   MissingLLMConfigurationError: () => MissingLLMConfigurationError,
+  Response: () => Response,
   Stagehand: () => V3,
   StagehandAPIError: () => StagehandAPIError,
   StagehandAPIUnauthorizedError: () => StagehandAPIUnauthorizedError,
@@ -6289,13 +7437,13 @@ module.exports = __toCommonJS(v3_exports);
 
 // lib/v3/v3.ts
 var import_dotenv = __toESM(require("dotenv"));
-var import_fs5 = __toESM(require("fs"));
+var import_fs6 = __toESM(require("fs"));
 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.0-preview.8";
+var STAGEHAND_VERSION = "3.0.1";
 
 // lib/v3/types/public/sdkErrors.ts
 var StagehandError = class extends Error {
@@ -7251,7 +8399,7 @@ var ActCache = class {
           }
         }
       });
-      return yield this.replayCachedActions(entry, page, timeout);
+      return yield this.replayCachedActions(context, entry, page, timeout);
     });
   }
   store(context, result) {
@@ -7301,7 +8449,7 @@ var ActCache = class {
     });
     return (0, import_crypto.createHash)("sha256").update(payload).digest("hex");
   }
-  replayCachedActions(entry, page, timeout) {
+  replayCachedActions(context, entry, page, timeout) {
     return __async(this, null, function* () {
       const handler = this.getActHandler();
       if (!handler) {
@@ -7337,6 +8485,13 @@ var ActCache = class {
         });
         const message = actionResults.map((r) => r.message).filter((m) => m && m.trim().length > 0).join(" \u2192 ") || entry.message || `Replayed ${entry.actions.length} cached action${entry.actions.length === 1 ? "" : "s"}.`;
         const actionDescription = entry.actionDescription || ((_b = actionResults[actionResults.length - 1]) == null ? void 0 : _b.actionDescription) || ((_c = entry.actions[entry.actions.length - 1]) == null ? void 0 : _c.description) || entry.instruction;
+        if (success && actions.length > 0 && this.haveActionsChanged(entry.actions, actions)) {
+          yield this.refreshCacheEntry(context, __spreadProps(__spreadValues({}, entry), {
+            actions,
+            message,
+            actionDescription
+          }));
+        }
         return {
           success,
           message,
@@ -7347,6 +8502,67 @@ var ActCache = class {
       return yield this.runWithTimeout(execute, timeout);
     });
   }
+  haveActionsChanged(original, updated) {
+    var _a, _b, _c, _d;
+    if (original.length !== updated.length) {
+      return true;
+    }
+    for (let i = 0; i < original.length; i += 1) {
+      const orig = original[i];
+      const next = updated[i];
+      if (!next) {
+        return true;
+      }
+      if (orig.selector !== next.selector) {
+        return true;
+      }
+      if (orig.description !== next.description) {
+        return true;
+      }
+      if (((_a = orig.method) != null ? _a : "") !== ((_b = next.method) != null ? _b : "")) {
+        return true;
+      }
+      const origArgs = (_c = orig.arguments) != null ? _c : [];
+      const nextArgs = (_d = next.arguments) != null ? _d : [];
+      if (origArgs.length !== nextArgs.length) {
+        return true;
+      }
+      for (let j = 0; j < origArgs.length; j += 1) {
+        if (origArgs[j] !== nextArgs[j]) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+  refreshCacheEntry(context, entry) {
+    return __async(this, null, function* () {
+      const { error, path: path6 } = yield this.storage.writeJson(
+        `${context.cacheKey}.json`,
+        entry
+      );
+      if (error && path6) {
+        this.logger({
+          category: "cache",
+          message: "failed to update act cache entry after self-heal",
+          level: 0,
+          auxiliary: {
+            error: { value: String(error), type: "string" }
+          }
+        });
+        return;
+      }
+      this.logger({
+        category: "cache",
+        message: "act cache entry updated after self-heal",
+        level: 2,
+        auxiliary: {
+          instruction: { value: context.instruction, type: "string" },
+          url: { value: context.pageUrl, type: "string" }
+        }
+      });
+    });
+  }
   runWithTimeout(run, timeout) {
     return __async(this, null, function* () {
       if (!timeout) {
@@ -9989,25 +11205,37 @@ function evaluateZodSchema(schemaStr, logger) {
       message: `Failed to evaluate schema: ${(_a = e == null ? void 0 : e.message) != null ? _a : String(e)}`,
       level: 0
     });
-    throw new Error(
-      "Invalid schema: Ensure you're passing a valid Zod schema expression, e.g. z.object({ title: z.string() })"
-    );
+    return import_v314.z.any();
   }
 }
 var createExtractTool = (v3, executionModel, logger) => (0, import_ai10.tool)({
-  description: "Extract structured data. Optionally provide an instruction and Zod schema.",
+  description: `Extract structured data from the current page based on a provided schema.
+    
+    USAGE GUIDELINES:
+    - Keep schemas MINIMAL - only include fields essential for the task
+    - IMPORANT: only use this if explicitly asked for structured output. In most scenarios, you should use the aria tree tool over this. 
+    - If you need to extract a link, make sure the type defintion follows the format of z.string().url()
+    EXAMPLES:
+    1. Extract a single value:
+       instruction: "extract the product price"
+       schema: "z.object({ price: z.number()})"
+    
+    2. Extract multiple fields:
+       instruction: "extract product name and price"
+       schema: "z.object({ name: z.string(), price: z.number() })"
+    
+    3. Extract arrays:
+       instruction: "extract all product names and prices"
+       schema: "z.object({ products: z.array(z.object({ name: z.string(), price: z.number() })) })"`,
   inputSchema: import_v314.z.object({
-    instruction: import_v314.z.string().optional(),
-    schema: import_v314.z.string().optional().describe("Zod schema as code, e.g. z.object({ title: z.string() })"),
-    selector: import_v314.z.string().optional()
+    instruction: import_v314.z.string(),
+    schema: import_v314.z.string().optional().describe("Zod schema as code, e.g. z.object({ title: z.string() })")
   }),
-  execute: (_0) => __async(null, [_0], function* ({ instruction, schema, selector }) {
+  execute: (_0) => __async(null, [_0], function* ({ instruction, schema }) {
     var _a;
     try {
       const parsedSchema = schema ? evaluateZodSchema(schema, logger) : void 0;
-      const result = yield v3.extract(instruction, parsedSchema, __spreadProps(__spreadValues({}, executionModel ? { model: executionModel } : {}), {
-        selector
-      }));
+      const result = yield v3.extract(instruction, parsedSchema, __spreadValues({}, executionModel ? { model: executionModel } : {}));
       return { success: true, result };
     } catch (error) {
       return { success: false, error: (_a = error == null ? void 0 : error.message) != null ? _a : String(error) };
@@ -10168,12 +11396,12 @@ function mapToolResultToActions({
     case "fillForm":
       return mapFillFormToolResult(toolResult, args, reasoning);
     default:
-      return [createStandardAction(toolCallName, args, reasoning)];
+      return [createStandardAction(toolCallName, toolResult, args, reasoning)];
   }
 }
 function mapActToolResult(toolResult, args, reasoning) {
   if (!toolResult || typeof toolResult !== "object") {
-    return [createStandardAction("act", args, reasoning)];
+    return [createStandardAction("act", toolResult, args, reasoning)];
   }
   const result = toolResult;
   const output = result.output || result;
@@ -10189,7 +11417,7 @@ function mapActToolResult(toolResult, args, reasoning) {
 }
 function mapFillFormToolResult(toolResult, args, reasoning) {
   if (!toolResult || typeof toolResult !== "object") {
-    return [createStandardAction("fillForm", args, reasoning)];
+    return [createStandardAction("fillForm", toolResult, args, reasoning)];
   }
   const result = toolResult;
   const output = result.output || result;
@@ -10210,12 +11438,17 @@ function mapFillFormToolResult(toolResult, args, reasoning) {
   }
   return actions;
 }
-function createStandardAction(toolCallName, args, reasoning) {
-  return __spreadValues({
+function createStandardAction(toolCallName, toolResult, args, reasoning) {
+  const action = __spreadValues({
     type: toolCallName,
     reasoning,
     taskCompleted: toolCallName === "close" ? args == null ? void 0 : args.taskComplete : false
   }, args);
+  if (toolCallName !== "ariaTree" && toolResult) {
+    const { output } = toolResult;
+    Object.assign(action, output);
+  }
+  return action;
 }
 
 // lib/v3/handlers/v3AgentHandler.ts
@@ -10360,7 +11593,7 @@ var V3AgentHandler = class {
   buildSystemPrompt(executionInstruction, systemInstructions) {
     if (systemInstructions) {
       return `${systemInstructions}
-Your current goal: ${executionInstruction}`;
+Your current goal: ${executionInstruction} when the task is complete, use the "close" tool with taskComplete: true`;
     }
     return `You are a web automation assistant using browser automation tools to accomplish the user's goal.
 
@@ -37288,6 +38521,111 @@ var LOG_LEVEL_NAMES = {
   2: "debug"
 };
 
+// lib/v3/types/public/page.ts
+init_consoleMessage();
+init_response();
+
+// examples/external_clients/aisdk.ts
+var import_ai14 = require("ai");
+var AISdkClient2 = class extends LLMClient {
+  constructor({ model }) {
+    super(model.modelId);
+    this.type = "aisdk";
+    this.model = model;
+  }
+  createChatCompletion(_0) {
+    return __async(this, arguments, function* ({
+      options
+    }) {
+      var _a, _b, _c, _d, _e, _f;
+      const formattedMessages = options.messages.map(
+        (message) => {
+          if (Array.isArray(message.content)) {
+            if (message.role === "system") {
+              const systemMessage = {
+                role: "system",
+                content: message.content.map((c) => "text" in c ? c.text : "").join("\n")
+              };
+              return systemMessage;
+            }
+            const contentParts = message.content.map((content) => {
+              if ("image_url" in content) {
+                const imageContent = {
+                  type: "image",
+                  image: content.image_url.url
+                };
+                return imageContent;
+              } else {
+                const textContent = {
+                  type: "text",
+                  text: content.text
+                };
+                return textContent;
+              }
+            });
+            if (message.role === "user") {
+              const userMessage = {
+                role: "user",
+                content: contentParts
+              };
+              return userMessage;
+            } else {
+              const textOnlyParts = contentParts.map((part) => ({
+                type: "text",
+                text: part.type === "image" ? "[Image]" : part.text
+              }));
+              const assistantMessage = {
+                role: "assistant",
+                content: textOnlyParts
+              };
+              return assistantMessage;
+            }
+          }
+          return {
+            role: message.role,
+            content: message.content
+          };
+        }
+      );
+      if (options.response_model) {
+        const response2 = yield (0, import_ai14.generateObject)({
+          model: this.model,
+          messages: formattedMessages,
+          schema: options.response_model.schema
+        });
+        return {
+          data: response2.object,
+          usage: {
+            prompt_tokens: (_a = response2.usage.inputTokens) != null ? _a : 0,
+            completion_tokens: (_b = response2.usage.outputTokens) != null ? _b : 0,
+            total_tokens: (_c = response2.usage.totalTokens) != null ? _c : 0
+          }
+        };
+      }
+      const tools = {};
+      for (const rawTool of options.tools) {
+        tools[rawTool.name] = {
+          description: rawTool.description,
+          inputSchema: rawTool.parameters
+        };
+      }
+      const response = yield (0, import_ai14.generateText)({
+        model: this.model,
+        messages: formattedMessages,
+        tools
+      });
+      return {
+        data: response.text,
+        usage: {
+          prompt_tokens: (_d = response.usage.inputTokens) != null ? _d : 0,
+          completion_tokens: (_e = response.usage.outputTokens) != null ? _e : 0,
+          total_tokens: (_f = response.usage.totalTokens) != null ? _f : 0
+        }
+      };
+    });
+  }
+};
+
 // lib/v3/understudy/context.ts
 init_logger();
 
@@ -38295,6 +39633,85 @@ var StagehandAPIClient = class {
       return response;
     });
   }
+  getReplayMetrics() {
+    return __async(this, null, function* () {
+      if (!this.sessionId) {
+        throw new StagehandAPIError("sessionId is required to fetch metrics.");
+      }
+      const response = yield this.request(`/sessions/${this.sessionId}/replay`, {
+        method: "GET"
+      });
+      if (response.status !== 200) {
+        const errorText = yield response.text();
+        this.logger({
+          category: "api",
+          message: `Failed to fetch metrics. Status ${response.status}: ${errorText}`,
+          level: 0
+        });
+        throw new StagehandHttpError(
+          `Failed to fetch metrics with status ${response.status}: ${errorText}`
+        );
+      }
+      const data = yield response.json();
+      if (!data.success) {
+        throw new StagehandAPIError(
+          `Failed to fetch metrics: ${data.error || "Unknown error"}`
+        );
+      }
+      const apiData = data.data || {};
+      const metrics = {
+        actPromptTokens: 0,
+        actCompletionTokens: 0,
+        actInferenceTimeMs: 0,
+        extractPromptTokens: 0,
+        extractCompletionTokens: 0,
+        extractInferenceTimeMs: 0,
+        observePromptTokens: 0,
+        observeCompletionTokens: 0,
+        observeInferenceTimeMs: 0,
+        agentPromptTokens: 0,
+        agentCompletionTokens: 0,
+        agentInferenceTimeMs: 0,
+        totalPromptTokens: 0,
+        totalCompletionTokens: 0,
+        totalInferenceTimeMs: 0
+      };
+      const pages = apiData.pages || [];
+      for (const page of pages) {
+        const actions = page.actions || [];
+        for (const action of actions) {
+          const method = (action.method || "").toLowerCase();
+          const tokenUsage = action.tokenUsage;
+          if (tokenUsage) {
+            const inputTokens = tokenUsage.inputTokens || 0;
+            const outputTokens = tokenUsage.outputTokens || 0;
+            const timeMs = tokenUsage.timeMs || 0;
+            if (method === "act") {
+              metrics.actPromptTokens += inputTokens;
+              metrics.actCompletionTokens += outputTokens;
+              metrics.actInferenceTimeMs += timeMs;
+            } else if (method === "extract") {
+              metrics.extractPromptTokens += inputTokens;
+              metrics.extractCompletionTokens += outputTokens;
+              metrics.extractInferenceTimeMs += timeMs;
+            } else if (method === "observe") {
+              metrics.observePromptTokens += inputTokens;
+              metrics.observeCompletionTokens += outputTokens;
+              metrics.observeInferenceTimeMs += timeMs;
+            } else if (method === "agent") {
+              metrics.agentPromptTokens += inputTokens;
+              metrics.agentCompletionTokens += outputTokens;
+              metrics.agentInferenceTimeMs += timeMs;
+            }
+            metrics.totalPromptTokens += inputTokens;
+            metrics.totalCompletionTokens += outputTokens;
+            metrics.totalInferenceTimeMs += timeMs;
+          }
+        }
+      }
+      return metrics;
+    });
+  }
   execute(_0) {
     return __async(this, arguments, function* ({
       method,
@@ -38501,11 +39918,12 @@ var _V3 = class _V3 {
     this.logInferenceToFile = (_f = opts.logInferenceToFile) != null ? _f : false;
     this.llmProvider = new LLMProvider(this.logger);
     this.domSettleTimeoutMs = opts.domSettleTimeout;
-    this.disableAPI = (_g = opts.disableAPI) != null ? _g : true;
+    this.disableAPI = (_g = opts.disableAPI) != null ? _g : false;
     const baseClientOptions = clientOptions ? __spreadValues({}, clientOptions) : {};
     if (opts.llmClient) {
       this.llmClient = opts.llmClient;
       this.modelClientOptions = baseClientOptions;
+      this.disableAPI = true;
     } else {
       let apiKey = baseClientOptions.apiKey;
       if (!apiKey) {
@@ -38556,11 +39974,24 @@ var _V3 = class _V3 {
     this.opts = opts;
     _V3._instances.add(this);
   }
+  get browserbaseSessionID() {
+    return this.browserbaseSessionId;
+  }
   /**
    * Async property for metrics so callers can `await v3.metrics`.
-   * Returning a Promise future-proofs async aggregation/storage.
+   * When using API mode, fetches metrics from the API. Otherwise returns local metrics.
    */
   get metrics() {
+    if (this.apiClient) {
+      return this.apiClient.getReplayMetrics().catch((error) => {
+        this.logger({
+          category: "metrics",
+          message: `Failed to fetch metrics from API: ${error}`,
+          level: 0
+        });
+        return this.stagehandMetrics;
+      });
+    }
     return Promise.resolve(this.stagehandMetrics);
   }
   resolveLlmClient(model) {
@@ -38835,8 +40266,8 @@ var _V3 = class _V3 {
             let createdTemp = false;
             if (!userDataDir) {
               const base = import_path5.default.join(import_os2.default.tmpdir(), "stagehand-v3");
-              import_fs5.default.mkdirSync(base, { recursive: true });
-              userDataDir = import_fs5.default.mkdtempSync(import_path5.default.join(base, "profile-"));
+              import_fs6.default.mkdirSync(base, { recursive: true });
+              userDataDir = import_fs6.default.mkdtempSync(import_path5.default.join(base, "profile-"));
               createdTemp = true;
             }
             const defaults2 = [
@@ -39265,7 +40696,7 @@ var _V3 = class _V3 {
           }
           try {
             if (this.state.createdTempProfile && !this.state.preserveUserDataDir && this.state.userDataDir) {
-              import_fs5.default.rmSync(this.state.userDataDir, { recursive: true, force: true });
+              import_fs6.default.rmSync(this.state.userDataDir, { recursive: true, force: true });
             }
           } catch (e) {
           }
@@ -39405,23 +40836,29 @@ var _V3 = class _V3 {
    * Mirrors the v2 Stagehand.agent() tool mode (no CUA provider here).
    */
   agent(options) {
-    var _a, _b, _c;
+    var _a, _b;
     this.logger({
       category: "agent",
-      message: "Creating v3 agent instance with options:",
+      message: `Creating v3 agent instance with options: ${JSON.stringify(options)}`,
       level: 1,
-      auxiliary: {
+      auxiliary: __spreadValues({
         cua: { value: (options == null ? void 0 : options.cua) ? "true" : "false", type: "boolean" },
-        model: typeof (options == null ? void 0 : options.model) === "string" ? { value: options.model, type: "string" } : { value: options.model.modelName, type: "string" },
+        model: (options == null ? void 0 : options.model) ? typeof (options == null ? void 0 : options.model) === "string" ? { value: options.model, type: "string" } : { value: options.model.modelName, type: "string" } : { value: this.llmClient.modelName, type: "string" },
         systemPrompt: { value: (_a = options == null ? void 0 : options.systemPrompt) != null ? _a : "", type: "string" },
-        tools: { value: JSON.stringify((_b = options == null ? void 0 : options.tools) != null ? _b : {}), type: "object" },
+        tools: { value: JSON.stringify((_b = options == null ? void 0 : options.tools) != null ? _b : {}), type: "object" }
+      }, (options == null ? void 0 : options.integrations) && {
         integrations: {
-          value: JSON.stringify((_c = options == null ? void 0 : options.integrations) != null ? _c : []),
+          value: JSON.stringify(options.integrations),
           type: "object"
         }
-      }
+      })
     });
     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."
+        );
+      }
       const modelToUse = (options == null ? void 0 : options.model) || __spreadValues({
         modelName: this.modelName
       }, this.modelClientOptions);
@@ -39519,9 +40956,9 @@ Do not ask follow up questions, the user will trust your judgement.`
       execute: (instructionOrOptions) => __async(this, null, function* () {
         return withInstanceLogContext(this.instanceId, () => __async(this, null, function* () {
           var _a2, _b2;
-          if ((options == null ? void 0 : options.integrations) && !this.experimental) {
+          if (((options == null ? void 0 : options.integrations) || (options == null ? void 0 : options.tools)) && !this.experimental) {
             throw new Error(
-              "MCP integrations are experimental. Enable experimental: true in V3 options."
+              "MCP integrations and custom tools are experimental. Enable experimental: true in V3 options."
             );
           }
           const tools = (options == null ? void 0 : options.integrations) ? yield resolveTools(options.integrations, options.tools) : (_a2 = options == null ? void 0 : options.tools) != null ? _a2 : {};
@@ -39826,12 +41263,14 @@ I'm providing ${screenshots.length} screenshots showing the progression of the t
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AISdkClient,
   AVAILABLE_CUA_MODELS,
   AgentProvider,
   AgentScreenshotProviderError,
   AnnotatedScreenshotText,
   BrowserbaseSessionNotFoundError,
   CaptchaTimeoutError,
+  ConsoleMessage,
   ContentFrameNotFoundError,
   CreateChatCompletionResponseError,
   ExperimentalApiConflictError,
@@ -39844,6 +41283,7 @@ I'm providing ${screenshots.length} screenshots showing the progression of the t
   MCPConnectionError,
   MissingEnvironmentVariableError,
   MissingLLMConfigurationError,
+  Response,
   Stagehand,
   StagehandAPIError,
   StagehandAPIUnauthorizedError,