stagehand 4.2.0a0.dev1590__tar.gz → 4.2.0a0.dev1591__tar.gz

{stagehand-4.2.0a0.dev1590 → stagehand-4.2.0a0.dev1591}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.2.0a0.dev1590
+Version: 4.2.0a0.dev1591
 Summary: Browserbase's SDK for building browser agents
 Keywords: ai,agent,ai-agent,browser,browser-agent,browser-automation,computer-use,headless,playwright,cdp,llm,automation,web-scraping,testing
 Author: Browserbase

{stagehand-4.2.0a0.dev1590 → stagehand-4.2.0a0.dev1591}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stagehand"
-version = "4.2.0a0.dev1590"
+version = "4.2.0a0.dev1591"
 description = "Browserbase's SDK for building browser agents"
 readme = "README.md"
 requires-python = ">=3.11"

{stagehand-4.2.0a0.dev1590 → stagehand-4.2.0a0.dev1591}/src/stagehand/_extension/content-script.js

@@ -990,7 +990,7 @@ var checkState = (el, state) => {
 /**
 * Set up MutationObservers on all shadow roots to detect changes.
 */
-var setupShadowObservers = (callback, observers) => {
+var setupShadowObservers = (callback, observers, isSettled) => {
 	const seenRoots = /* @__PURE__ */ new WeakSet();
 	const observeShadowRoots = (node) => {
 		const shadowRoot = getOpenOrClosedShadowRoot(node);
@@ -1000,6 +1000,7 @@ var setupShadowObservers = (callback, observers) => {
 				callback();
 				scan();
 			});
+			observers.push(shadowObserver);
 			shadowObserver.observe(shadowRoot, {
 				childList: true,
 				subtree: true,
@@ -1011,14 +1012,13 @@ var setupShadowObservers = (callback, observers) => {
 					"disabled"
 				]
 			});
-			observers.push(shadowObserver);
 			for (const child of Array.from(shadowRoot.children)) observeShadowRoots(child);
 		}
 		for (const child of Array.from(node.children)) observeShadowRoots(child);
 	};
 	const root = document.documentElement || document.body;
 	const scan = () => {
-		if (root) observeShadowRoots(root);
+		if (!isSettled() && root) observeShadowRoots(root);
 	};
 	scan();
 	return scan;
@@ -1029,106 +1029,99 @@ var setupShadowObservers = (callback, observers) => {
 *
 * @param selectorRaw - CSS selector or XPath expression to wait for
 * @param stateRaw - Element state: 'attached' | 'detached' | 'visible' | 'hidden'
-* @param timeoutRaw - Maximum time to wait in milliseconds
+* @param timeoutRaw - Maximum time to wait in milliseconds; defaults to 30,000, zero is unlimited
 * @param pierceShadowRaw - Whether to search inside shadow DOM
-* @returns Promise that resolves to true when condition is met, or rejects on timeout
+* @returns A disposable handle whose promise resolves when the condition is met
 */
-function waitForSelector(selectorRaw, stateRaw, timeoutRaw, pierceShadowRaw) {
+function createSelectorWait(selectorRaw, stateRaw, timeoutRaw, pierceShadowRaw) {
 	const selector = String(selectorRaw ?? "").trim();
 	const state = String(stateRaw ?? "visible") || "visible";
-	const timeout = typeof timeoutRaw === "number" && timeoutRaw > 0 ? timeoutRaw : 3e4;
+	const timeout = typeof timeoutRaw === "number" && timeoutRaw >= 0 ? timeoutRaw : 3e4;
 	const pierceShadow = pierceShadowRaw !== false;
-	return new Promise((resolve, reject) => {
-		let timeoutId = null;
-		let domReadyHandler = null;
+	let dispose = () => {};
+	const promise = new Promise((resolve, reject) => {
 		let settled = false;
-		const clearTimer = () => {
-			if (timeoutId !== null) {
-				clearTimeout(timeoutId);
-				timeoutId = null;
-			}
-		};
-		if (checkState(findElement(selector, pierceShadow), state)) {
-			settled = true;
-			resolve(true);
-			return;
-		}
+		let timeoutId;
+		let shadowScanInterval;
+		let domReadyHandler;
+		let rescanShadowRoots;
 		const observers = [];
-		let shadowScanInterval = null;
-		let rescanShadowRoots = null;
-		const cleanup = () => {
-			for (const obs of observers) obs.disconnect();
-			if (shadowScanInterval !== null) {
-				clearInterval(shadowScanInterval);
-				shadowScanInterval = null;
-			}
+		const settle = (error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeoutId);
+			clearInterval(shadowScanInterval);
+			for (const observer of observers) observer.disconnect();
+			observers.length = 0;
+			rescanShadowRoots = void 0;
 			if (domReadyHandler) {
 				document.removeEventListener("DOMContentLoaded", domReadyHandler);
-				domReadyHandler = null;
+				domReadyHandler = void 0;
 			}
+			if (error) reject(error);
+			else resolve(true);
 		};
+		dispose = () => settle(/* @__PURE__ */ new Error("Selector wait disposed"));
 		const check = () => {
 			if (settled) return;
-			if (checkState(findElement(selector, pierceShadow), state)) {
-				settled = true;
-				clearTimer();
-				cleanup();
-				resolve(true);
+			try {
+				if (checkState(findElement(selector, pierceShadow), state)) settle();
+			} catch (error) {
+				settle(error instanceof Error ? error : new Error(String(error)));
 			}
 		};
-		if (!(document.body || document.documentElement)) {
+		const setupObservers = () => {
+			if (settled) return;
+			const root = document.body || document.documentElement;
+			if (!root) return;
+			try {
+				const mainObserver = new MutationObserver(() => {
+					check();
+					rescanShadowRoots?.();
+				});
+				observers.push(mainObserver);
+				mainObserver.observe(root, {
+					childList: true,
+					subtree: true,
+					attributes: true,
+					attributeFilter: [
+						"style",
+						"class",
+						"hidden",
+						"disabled"
+					]
+				});
+				if (pierceShadow) {
+					rescanShadowRoots = setupShadowObservers(check, observers, () => settled);
+					shadowScanInterval = setInterval(() => {
+						rescanShadowRoots?.();
+						check();
+					}, 100);
+				}
+			} catch (error) {
+				settle(error instanceof Error ? error : new Error(String(error)));
+			}
+		};
+		check();
+		if (settled) return;
+		if (document.body || document.documentElement) setupObservers();
+		else {
 			domReadyHandler = () => {
+				if (settled) return;
 				document.removeEventListener("DOMContentLoaded", domReadyHandler);
-				domReadyHandler = null;
+				domReadyHandler = void 0;
 				check();
 				setupObservers();
 			};
 			document.addEventListener("DOMContentLoaded", domReadyHandler);
-			timeoutId = setTimeout(() => {
-				if (settled) return;
-				settled = true;
-				clearTimer();
-				cleanup();
-				reject(/* @__PURE__ */ new Error(`waitForSelector: Timeout ${timeout}ms exceeded waiting for "${selector}" to be ${state}`));
-			}, timeout);
-			return;
 		}
-		const setupObservers = () => {
-			const root = document.body || document.documentElement;
-			if (!root) return;
-			const mainObserver = new MutationObserver(() => {
-				check();
-				rescanShadowRoots?.();
-			});
-			mainObserver.observe(root, {
-				childList: true,
-				subtree: true,
-				attributes: true,
-				attributeFilter: [
-					"style",
-					"class",
-					"hidden",
-					"disabled"
-				]
-			});
-			observers.push(mainObserver);
-			if (pierceShadow) {
-				rescanShadowRoots = setupShadowObservers(check, observers);
-				shadowScanInterval = setInterval(() => {
-					rescanShadowRoots?.();
-					check();
-				}, 100);
-			}
-		};
-		setupObservers();
-		timeoutId = setTimeout(() => {
-			if (settled) return;
-			settled = true;
-			clearTimer();
-			cleanup();
-			reject(/* @__PURE__ */ new Error(`waitForSelector: Timeout ${timeout}ms exceeded waiting for "${selector}" to be ${state}`));
-		}, timeout);
+		if (!settled && timeout > 0) timeoutId = setTimeout(() => settle(/* @__PURE__ */ new Error(`waitForSelector: Timeout ${timeout}ms exceeded waiting for "${selector}" to be ${state}`)), timeout);
 	});
+	promise.catch(() => {});
+	return {
+		promise,
+		dispose: () => dispose()
+	};
 }
 //#endregion
 //#region dom/locatorScripts/registry.ts
@@ -1142,7 +1135,7 @@ var locatorScripts = Object.freeze({
 	resolveCssSelector,
 	resolveTextSelector,
 	resolveXPathMainWorld,
-	waitForSelector
+	createSelectorWait
 });
 //#endregion
 //#region content-script.ts

{stagehand-4.2.0a0.dev1590 → stagehand-4.2.0a0.dev1591}/src/stagehand/_extension/service-worker.js

@@ -7363,7 +7363,7 @@ function isRecord$1(value) {
 }
 var package_default$1 = {
 	name: "@browserbasehq/stagehand-protocol",
-	version: "2.1.0-alpha-535b80d78b84a5ad3ead386d5399029bb873b80e",
+	version: "2.1.0-alpha-7d8dcef8765f0a9dce498e1cc9d68c6b91ac3892",
 	"private": true,
 	type: "module",
 	exports: {
@@ -17071,33 +17071,82 @@ var Frame = class {
 		return res.result.value;
 	}
 	/** Evaluate an internal expression in Stagehand's selected locator world. */
-	async evaluateInLocatorWorld(expression, progress) {
+	async evaluateInLocatorWorld(buildExpression, progress) {
+		const response = await this.evaluateLocatorExpression(buildExpression, { progress });
+		if (response.exceptionDetails) throw new Error(response.exceptionDetails.text ?? "Locator-world evaluation failed");
+		return response.result.value;
+	}
+	/** Own a disposable browser wait, including a handle delivered after expiry. */
+	async waitInLocatorWorld(buildExpression, progress) {
+		const dispose = (objectId) => Promise.all([progress.cleanup(() => this.session.send("Runtime.callFunctionOn", {
+			objectId,
+			functionDeclaration: "function() { this.dispose(); }",
+			returnByValue: true
+		})), progress.cleanup(() => this.session.send("Runtime.releaseObject", { objectId }))]);
+		for (let attempt = 0;; attempt++) {
+			progress.throwIfStopped();
+			const response = await this.evaluateLocatorExpression(buildExpression, {
+				progress,
+				returnByValue: false,
+				awaitPromise: false,
+				onLateResult: async (late) => {
+					if (late.result.objectId) await dispose(late.result.objectId);
+				}
+			});
+			const objectId = response.result.objectId;
+			let completed = false;
+			try {
+				if (response.exceptionDetails || !objectId) throw new Error(response.exceptionDetails?.exception?.description ?? response.exceptionDetails?.text ?? "Selector wait handle was not returned");
+				let result;
+				try {
+					result = await progress.run("waiting for selector", () => this.session.send("Runtime.callFunctionOn", {
+						objectId,
+						functionDeclaration: "function() { return this.promise; }",
+						awaitPromise: true,
+						returnByValue: true
+					}));
+				} catch (error) {
+					progress.throwIfStopped();
+					const message = error instanceof Error ? error.message : String(error);
+					if (attempt !== 0 || !message.includes("Cannot find context with specified id")) throw error;
+					executionContexts.unregisterLocatorContext(this.session, response.contextId);
+					continue;
+				}
+				if (result.exceptionDetails) throw new Error(result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Selector wait failed");
+				completed = true;
+				return result.result.value;
+			} finally {
+				if (objectId) if (completed) progress.cleanup(() => this.session.send("Runtime.releaseObject", { objectId }));
+				else await dispose(objectId);
+			}
+		}
+	}
+	async evaluateLocatorExpression(buildExpression, options) {
+		const { progress } = options;
 		await runLocatorStep(progress, "enabling runtime", () => this.session.send("Runtime.enable").catch((error) => {
 			if (progress && isCdpClosedError(error)) throw error;
 		}));
 		let locatorWorld = await executionContexts.waitForLocatorWorld(this.session, this.frameId, 1e3, progress);
+		const evaluate = () => runLocatorStep(progress, "evaluating locator helper", () => this.session.send("Runtime.evaluate", {
+			expression: buildExpression(),
+			contextId: locatorWorld.contextId,
+			awaitPromise: options.awaitPromise ?? true,
+			returnByValue: options.returnByValue ?? true
+		}), options.onLateResult);
 		let response;
 		try {
-			response = await runLocatorStep(progress, "evaluating locator helper", () => this.session.send("Runtime.evaluate", {
-				expression,
-				contextId: locatorWorld.contextId,
-				awaitPromise: true,
-				returnByValue: true
-			}));
+			response = await evaluate();
 		} catch (error) {
 			progress?.throwIfStopped();
 			if (!(error instanceof Error ? error.message : String(error)).includes("Cannot find context with specified id")) throw error;
 			executionContexts.unregisterLocatorContext(this.session, locatorWorld.contextId);
 			locatorWorld = await executionContexts.waitForLocatorWorld(this.session, this.frameId, 1e3, progress);
-			response = await runLocatorStep(progress, "evaluating locator helper", () => this.session.send("Runtime.evaluate", {
-				expression,
-				contextId: locatorWorld.contextId,
-				awaitPromise: true,
-				returnByValue: true
-			}));
+			response = await evaluate();
 		}
-		if (response.exceptionDetails) throw new Error(response.exceptionDetails.text ?? "Locator-world evaluation failed");
-		return response.result.value;
+		return {
+			...response,
+			contextId: locatorWorld.contextId
+		};
 	}
 	/** Page.captureScreenshot (frame-scoped session) */
 	async screenshot(options, progress) {
@@ -54394,7 +54443,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.1.0-alpha-535b80d78b84a5ad3ead386d5399029bb873b80e",
+	version: "1.1.0-alpha-7d8dcef8765f0a9dce498e1cc9d68c6b91ac3892",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -56333,7 +56382,7 @@ var Page = class Page {
 		this.initScripts.push(source);
 	}
 	async ensureCursorScript() {
-		await this.mainFrameWrapper.evaluateInLocatorWorld("globalThis.__stagehandLocatorScripts.installCursorOverlay()").catch(() => {});
+		await this.mainFrameWrapper.evaluateInLocatorWorld(() => "globalThis.__stagehandLocatorScripts.installCursorOverlay()").catch(() => {});
 	}
 	async enableCursorOverlay() {
 		if (this.cursorEnabled) return;
@@ -56343,7 +56392,7 @@ var Page = class Page {
 	async updateCursor(x, y, progress) {
 		if (!this.cursorEnabled) return;
 		try {
-			await this.mainFrameWrapper.evaluateInLocatorWorld(`globalThis.__stagehandLocatorScripts.moveCursorOverlay(${Math.round(x)}, ${Math.round(y)})`, progress);
+			await this.mainFrameWrapper.evaluateInLocatorWorld(() => `globalThis.__stagehandLocatorScripts.moveCursorOverlay(${Math.round(x)}, ${Math.round(y)})`, progress);
 		} catch {
 			progress?.throwIfStopped();
 		}
@@ -57356,27 +57405,28 @@ var Page = class Page {
 	* @param selector CSS selector to wait for (supports '>>' for iframe hops)
 	* @param options
 	* @param options.state Element state to wait for: 'attached' | 'detached' | 'visible' | 'hidden' (default: 'visible')
-	* @param options.timeout Maximum time to wait in milliseconds (default: 30000)
+	* @param options.timeout Maximum time to wait in milliseconds (default: 30000; zero is unlimited)
 	* @param options.pierceShadow Whether to search inside shadow DOM (default: true)
 	* @returns True when the condition is met
 	* @throws Error if timeout is reached before the condition is met
 	*/
-	async waitForSelector(selector, options) {
-		const timeout = options?.timeout ?? 3e4;
-		const state = options?.state ?? "visible";
-		const pierceShadow = options?.pierceShadow ?? true;
-		const startTime = Date.now();
-		const root = this.mainFrameWrapper;
-		const { frame: targetFrame, selector: finalSelector } = await resolveLocatorTarget(this, root, selector);
-		const elapsed = Date.now() - startTime;
-		const remainingTimeout = Math.max(0, timeout - elapsed);
-		const expression = buildLocatorInvocation("waitForSelector", [
-			JSON.stringify(finalSelector),
-			JSON.stringify(state),
-			String(remainingTimeout),
-			String(pierceShadow)
-		]);
-		return targetFrame.evaluateInLocatorWorld(expression);
+	async waitForSelector(selector, options, parentProgress) {
+		return runWithProgress(parentProgress ?? {
+			name: "waitForSelector",
+			timeout: options?.timeout ?? 3e4
+		}, async (progress) => {
+			const { frame: targetFrame, selector: finalSelector } = await resolveLocatorTarget(this, this.mainFrameWrapper, selector, progress);
+			return targetFrame.waitInLocatorWorld(() => {
+				const remaining = progress.remainingMs();
+				progress.throwIfStopped();
+				return buildLocatorInvocation("createSelectorWait", [
+					JSON.stringify(finalSelector),
+					JSON.stringify(options?.state ?? "visible"),
+					String(remaining === Infinity ? 0 : Math.ceil(remaining)),
+					String(options?.pierceShadow ?? true)
+				]);
+			}, progress);
+		});
 	}
 	/** Internal batch evaluation; page.evaluate continues to use the main world unchanged. */
 	async evaluateWithShadowRoots(functionSource) {

{stagehand-4.2.0a0.dev1590 → stagehand-4.2.0a0.dev1591}/src/stagehand/_generated/protocol_version.py

@@ -1,4 +1,4 @@
 """Generated from packages/protocol/package.json. Do not edit."""
 
 PROTOCOL_SEMVER_PATTERN = '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\\+([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?$'
-STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-535b80d78b84a5ad3ead386d5399029bb873b80e'
+STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-7d8dcef8765f0a9dce498e1cc9d68c6b91ac3892'

{stagehand-4.2.0a0.dev1590 → stagehand-4.2.0a0.dev1591}/src/stagehand/rpc_client.py

@@ -569,7 +569,10 @@ def _rpc_response_timeout_seconds(method: str, params: BaseModel) -> float | Non
         operation_timeout_ms = _numeric_property(params, "ms")
 
     if operation_timeout_ms is not None:
-        if method in {"page.pdf", "page.snapshot"} and operation_timeout_ms == 0:
+        if (
+            method in {"page.pdf", "page.snapshot", "page.wait_for_selector"}
+            and operation_timeout_ms == 0
+        ):
             return None
         return (_RPC_RESPONSE_GRACE_MS + max(0, operation_timeout_ms)) / 1_000