stagehand 4.2.0a0.dev1560__tar.gz → 4.2.0a0.dev1562__tar.gz

{stagehand-4.2.0a0.dev1560 → stagehand-4.2.0a0.dev1562}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stagehand
-Version: 4.2.0a0.dev1560
+Version: 4.2.0a0.dev1562
 Summary: Browserbase's SDK for building browser agents
 Keywords: ai,browser,automation,web-scraping,testing
 Author: Browserbase

{stagehand-4.2.0a0.dev1560 → stagehand-4.2.0a0.dev1562}/pyproject.toml

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

{stagehand-4.2.0a0.dev1560 → stagehand-4.2.0a0.dev1562}/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-c88a64f8d48d13e5e4d43d14fd9e54e388de3383",
+	version: "2.1.0-alpha-666b6fa32b003420a4a9e641dc47ee4c9a531eff",
 	"private": true,
 	type: "module",
 	exports: {
@@ -8324,7 +8324,10 @@ var SnapshotResultSchema = strictObject({
 	xpathMap: record(string(), string()),
 	urlMap: record(string(), string())
 }).meta({ id: "SnapshotResult" });
-var PageSnapshotOptionsSchema = strictObject({ includeIframes: boolean().optional() }).meta({ id: "PageSnapshotOptions" });
+var PageSnapshotOptionsSchema = strictObject({
+	timeout: number$1().nonnegative().optional().describe("Milliseconds for the whole snapshot call. Defaults to 20000. Zero disables the timeout."),
+	includeIframes: boolean().optional()
+}).meta({ id: "PageSnapshotOptions" });
 var PageRefSchema = strictObject({
 	pageId: string(),
 	url: string().optional(),
@@ -14073,9 +14076,10 @@ var ExecutionContextRegistry = class {
 		return this.fallbackByFrame.get(session)?.get(frameId) ?? null;
 	}
 	/** With progress, timeout limits each extension probe, not the whole wait.
-	* Frame traversal disables retries here so it can recheck session ownership.
+	* Callers that handle failure themselves can disable retries without losing
+	* the caller's deadline. Without progress, readiness makes a single attempt.
 	*/
-	async waitForLocatorWorld(session, frameId, timeout = 1e3, progress, retryUntilDeadline = true) {
+	async waitForLocatorWorld(session, frameId, timeout = 1e3, progress, { readinessRetries = "until-deadline" } = {}) {
 		while (true) {
 			progress?.throwIfStopped();
 			const extensionContextId = this.getExtensionWorld(session, frameId);
@@ -14088,7 +14092,7 @@ var ExecutionContextRegistry = class {
 				progress?.throwIfStopped();
 				if (progress && isCdpClosedError(extensionError)) throw extensionError;
 				if (await this.isFallbackEligible(session, frameId, progress)) return this.fallbackWorld(await runLocatorStep(progress, "installing locator helpers", () => this.createFallbackWorld(session, frameId)));
-				if (!progress || !retryUntilDeadline) throw extensionError;
+				if (!progress || readinessRetries === "none") throw extensionError;
 			}
 		}
 	}
@@ -14389,8 +14393,9 @@ function buildLocatorInvocation(name, args) {
 //#endregion
 //#region understudy/selectorResolver.ts
 var FrameSelectorResolver = class {
-	constructor(frame) {
+	constructor(frame, readinessOptions = {}) {
 		this.frame = frame;
+		this.readinessOptions = readinessOptions;
 	}
 	static parseSelector(raw) {
 		const trimmed = raw.trim();
@@ -14466,7 +14471,7 @@ var FrameSelectorResolver = class {
 	async resolveElements(helper, value, limit, progress) {
 		progress?.throwIfStopped();
 		if (limit <= 0) return [];
-		const { contextId } = await executionContexts.waitForLocatorWorld(this.frame.session, this.frame.frameId, 1e3, progress);
+		const { contextId } = await executionContexts.waitForLocatorWorld(this.frame.session, this.frame.frameId, 1e3, progress, this.readinessOptions);
 		const results = [];
 		try {
 			for (let index = 0; index < limit; index += 1) {
@@ -14488,13 +14493,13 @@ var FrameSelectorResolver = class {
 	}
 	async countCss(selector, progress) {
 		const session = this.frame.session;
-		const { contextId } = await executionContexts.waitForLocatorWorld(session, this.frame.frameId, 1e3, progress);
+		const { contextId } = await executionContexts.waitForLocatorWorld(session, this.frame.frameId, 1e3, progress, this.readinessOptions);
 		const primaryExpr = buildLocatorInvocation("countCssMatchesPrimary", [JSON.stringify(selector)]);
 		return this.evaluateCount(primaryExpr, contextId, progress);
 	}
 	async countText(value, progress) {
 		const session = this.frame.session;
-		const { contextId: ctxId } = await executionContexts.waitForLocatorWorld(session, this.frame.frameId, 1e3, progress);
+		const { contextId: ctxId } = await executionContexts.waitForLocatorWorld(session, this.frame.frameId, 1e3, progress, this.readinessOptions);
 		const expr = buildLocatorInvocation("countTextMatches", [JSON.stringify(value)]);
 		try {
 			const evalRes = await runLocatorStep(progress, "counting elements", () => session.send("Runtime.evaluate", {
@@ -14525,7 +14530,7 @@ var FrameSelectorResolver = class {
 	}
 	async countXPath(value, progress) {
 		const session = this.frame.session;
-		const { contextId: ctxId } = await executionContexts.waitForLocatorWorld(session, this.frame.frameId, 1e3, progress);
+		const { contextId: ctxId } = await executionContexts.waitForLocatorWorld(session, this.frame.frameId, 1e3, progress, this.readinessOptions);
 		const expr = buildLocatorInvocation("countXPathMatchesMainWorld", [JSON.stringify(value)]);
 		try {
 			const evalRes = await runLocatorStep(progress, "counting elements", () => session.send("Runtime.evaluate", {
@@ -15533,7 +15538,7 @@ async function ensureChildFrameReady(page, childFrameId, budgetMs, progress) {
 		const remaining = progress?.remainingMs() ?? deadline - Date.now();
 		if (remaining <= 0) break;
 		try {
-			await executionContexts.waitForLocatorWorld(session, childFrameId, Math.min(remaining, LOCATOR_WORLD_ATTEMPT_TIMEOUT_MS), progress, false);
+			await executionContexts.waitForLocatorWorld(session, childFrameId, Math.min(remaining, LOCATOR_WORLD_ATTEMPT_TIMEOUT_MS), progress, { readinessRetries: "none" });
 			progress?.throwIfStopped();
 			if (page.getSessionForFrame(childFrameId) === session) return;
 		} catch (error) {
@@ -15638,7 +15643,8 @@ var IFRAME_STEP_RE = /^i?frame(?:\[\d+])?$/i;
 * - the tail XPath (within the target frame)
 * - the absolute XPath prefix up to the iframe element hosting that frame
 */
-async function resolveFocusFrameAndTail(page, absoluteXPath, parentByFrame, rootId) {
+async function resolveFocusFrameAndTail(page, absoluteXPath, parentByFrame, rootId, progress) {
+	progress?.throwIfStopped();
 	const steps = parseXPathToSteps(absoluteXPath);
 	let ctxFrameId = rootId;
 	let buf = [];
@@ -15647,33 +15653,36 @@ async function resolveFocusFrameAndTail(page, absoluteXPath, parentByFrame, root
 		if (!buf.length) return;
 		const selectorForIframe = buildXPathFromSteps$1(buf);
 		const parentSess = page.getSessionForFrame(ctxFrameId);
-		const objectId = await resolveObjectIdForXPath(parentSess, selectorForIframe, ctxFrameId);
+		const objectId = await resolveObjectIdForXPath(parentSess, selectorForIframe, ctxFrameId, 0, progress);
 		if (!objectId) throw iframeResolutionError(selectorForIframe, "Failed to resolve iframe element by XPath");
 		try {
-			await parentSess.send("DOM.enable").catch(() => {});
-			const iframeBackendNodeId = (await parentSess.send("DOM.describeNode", { objectId })).node.backendNodeId;
+			await runLocatorStep(progress, "enabling DOM", () => parentSess.send("DOM.enable").catch(() => {}));
+			const iframeBackendNodeId = (await runLocatorStep(progress, "reading snapshot iframe", () => parentSess.send("DOM.describeNode", { objectId }))).node.backendNodeId;
 			let childFrameId;
 			for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) try {
-				const { backendNodeId } = await parentSess.send("DOM.getFrameOwner", { frameId: fid });
+				const { backendNodeId } = await runLocatorStep(progress, "finding snapshot iframe owner", () => parentSess.send("DOM.getFrameOwner", { frameId: fid }));
 				if (backendNodeId === iframeBackendNodeId) {
 					childFrameId = fid;
 					break;
 				}
 			} catch {
+				progress?.throwIfStopped();
 				continue;
 			}
 			if (!childFrameId) throw iframeResolutionError(selectorForIframe, "Could not map iframe to child frameId");
 			absPrefix = prefixXPath(absPrefix || "/", selectorForIframe);
 			ctxFrameId = childFrameId;
 		} finally {
-			await parentSess.send("Runtime.releaseObject", { objectId }).catch(() => {});
+			await releaseSnapshotObject(parentSess, objectId, progress);
 		}
 		buf = [];
 	};
 	for (const st of steps) {
+		progress?.throwIfStopped();
 		buf.push(st);
 		if (IFRAME_STEP_RE.test(st.name)) await flushIntoChild();
 	}
+	progress?.throwIfStopped();
 	const tailXPath = buildXPathFromSteps$1(buf);
 	return {
 		targetFrameId: ctxFrameId,
@@ -15682,33 +15691,36 @@ async function resolveFocusFrameAndTail(page, absoluteXPath, parentByFrame, root
 	};
 }
 /** Resolve focus frame and tail CSS selector using '>>' to hop iframes. */
-async function resolveCssFocusFrameAndTail(page, rawSelector, parentByFrame, rootId) {
+async function resolveCssFocusFrameAndTail(page, rawSelector, parentByFrame, rootId, progress) {
+	progress?.throwIfStopped();
 	const parts = rawSelector.split(">>").map((s) => s.trim()).filter(Boolean);
 	let ctxFrameId = rootId;
 	const absPrefix = "";
 	for (let i = 0; i < Math.max(0, parts.length - 1); i++) {
 		const parentSess = page.getSessionForFrame(ctxFrameId);
-		const objectId = await resolveObjectIdForCss(parentSess, parts[i], ctxFrameId);
+		const objectId = await resolveObjectIdForCss(parentSess, parts[i], ctxFrameId, 0, progress);
 		if (!objectId) throw iframeResolutionError(parts[i], "Failed to resolve iframe via CSS hop");
 		try {
-			await parentSess.send("DOM.enable").catch(() => {});
-			const iframeBackendNodeId = (await parentSess.send("DOM.describeNode", { objectId })).node.backendNodeId;
+			await runLocatorStep(progress, "enabling DOM", () => parentSess.send("DOM.enable").catch(() => {}));
+			const iframeBackendNodeId = (await runLocatorStep(progress, "reading snapshot iframe", () => parentSess.send("DOM.describeNode", { objectId }))).node.backendNodeId;
 			let childFrameId;
 			for (const fid of listChildrenOf(parentByFrame, ctxFrameId)) try {
-				const { backendNodeId } = await parentSess.send("DOM.getFrameOwner", { frameId: fid });
+				const { backendNodeId } = await runLocatorStep(progress, "finding snapshot iframe owner", () => parentSess.send("DOM.getFrameOwner", { frameId: fid }));
 				if (backendNodeId === iframeBackendNodeId) {
 					childFrameId = fid;
 					break;
 				}
 			} catch {
+				progress?.throwIfStopped();
 				continue;
 			}
 			if (!childFrameId) throw iframeResolutionError(parts[i], "Could not map CSS iframe hop to child frameId");
 			ctxFrameId = childFrameId;
 		} finally {
-			await parentSess.send("Runtime.releaseObject", { objectId }).catch(() => {});
+			await releaseSnapshotObject(parentSess, objectId, progress);
 		}
 	}
+	progress?.throwIfStopped();
 	const tailSelector = parts[parts.length - 1] ?? "*";
 	return {
 		targetFrameId: ctxFrameId,
@@ -15720,35 +15732,36 @@ function iframeResolutionError(frameUrl, message) {
 	return /* @__PURE__ */ new Error(`Unable to resolve frameId for iframe with URL: ${frameUrl} Full error: ${message}`);
 }
 /** Resolve an XPath to a Runtime remoteObjectId in the given CDP session. */
-async function resolveObjectIdForXPath(session, xpath, frameId, index = 0) {
-	let contextId;
-	if (frameId) contextId = (await executionContexts.waitForLocatorWorld(session, frameId, 800)).contextId;
-	const expr = buildLocatorInvocation("resolveXPathMainWorld", [JSON.stringify(xpath), JSON.stringify(index)]);
-	const { result, exceptionDetails } = await session.send("Runtime.evaluate", {
-		expression: expr,
+async function resolveObjectIdForXPath(session, xpath, frameId, index = 0, progress) {
+	return resolveObjectId(session, buildLocatorInvocation("resolveXPathMainWorld", [JSON.stringify(xpath), JSON.stringify(index)]), frameId, progress);
+}
+/** Resolve a CSS selector (supports '>>' within the same frame only) to a Runtime objectId. */
+async function resolveObjectIdForCss(session, selector, frameId, index = 0, progress) {
+	return resolveObjectId(session, buildLocatorInvocation("resolveCssSelector", [JSON.stringify(selector), JSON.stringify(index)]), frameId, progress);
+}
+async function resolveObjectId(session, expression, frameId, progress) {
+	progress?.throwIfStopped();
+	const contextId = frameId ? (await executionContexts.waitForLocatorWorld(session, frameId, 800, progress, { readinessRetries: "none" })).contextId : void 0;
+	const release = (response) => releaseSnapshotObject(session, response.result?.objectId, progress);
+	const response = await runLocatorStep(progress, "resolving snapshot focus", () => session.send("Runtime.evaluate", {
+		expression,
 		returnByValue: false,
 		contextId,
 		awaitPromise: true
-	});
-	if (exceptionDetails) return null;
-	return result?.objectId ?? null;
+	}), release);
+	if (response.exceptionDetails) {
+		await release(response);
+		progress?.throwIfStopped();
+		return null;
+	}
+	return response.result?.objectId ?? null;
 }
-/** Resolve a CSS selector (supports '>>' within the same frame only) to a Runtime objectId. */
-async function resolveObjectIdForCss(session, selector, frameId, index = 0) {
-	let contextId;
-	if (frameId) contextId = (await executionContexts.waitForLocatorWorld(session, frameId, 800)).contextId;
-	const expression = buildLocatorInvocation("resolveCssSelector", [JSON.stringify(selector), JSON.stringify(index)]);
-	const evaluate = async (expression) => {
-		const { result, exceptionDetails } = await session.send("Runtime.evaluate", {
-			expression,
-			returnByValue: false,
-			contextId,
-			awaitPromise: true
-		});
-		if (exceptionDetails) return null;
-		return result?.objectId ?? null;
-	};
-	return evaluate(expression);
+/** Release snapshot references even after expiry, without replacing the read error. */
+async function releaseSnapshotObject(session, objectId, progress) {
+	if (!objectId) return;
+	const release = () => session.send("Runtime.releaseObject", { objectId }).catch(() => {});
+	if (progress) await progress.cleanup(release);
+	else await release();
 }
 function listChildrenOf(parentByFrame, parentId) {
 	const out = [];
@@ -17307,31 +17320,33 @@ function normaliseSpaces(s) {
 * Fetch and prune the accessibility tree for a frame, optionally scoping the
 * output to a selector root for faster targeted snapshots.
 */
-async function a11yForFrame(session, frameId, opts) {
-	await session.send("Accessibility.enable").catch(() => {});
-	await session.send("Runtime.enable").catch(() => {});
-	await session.send("DOM.enable").catch(() => {});
+async function a11yForFrame(session, frameId, opts, progress) {
+	await runLocatorStep(progress, "enabling Accessibility", () => session.send("Accessibility.enable").catch(() => {}));
+	await runLocatorStep(progress, "enabling Runtime", () => session.send("Runtime.enable").catch(() => {}));
+	await runLocatorStep(progress, "enabling DOM", () => session.send("DOM.enable").catch(() => {}));
 	let nodes = [];
 	try {
 		const params = frameId ? { frameId } : {};
-		({nodes} = await session.send("Accessibility.getFullAXTree", params));
+		({nodes} = await runLocatorStep(progress, "reading snapshot accessibility tree", () => session.send("Accessibility.getFullAXTree", params)));
 	} catch (e) {
+		progress?.throwIfStopped();
 		const msg = String(e?.message ?? e ?? "");
 		if (!(msg.includes("Frame with the given") || msg.includes("does not belong to the target") || msg.includes("is not found")) || !frameId) throw e;
-		({nodes} = await session.send("Accessibility.getFullAXTree"));
+		({nodes} = await runLocatorStep(progress, "reading snapshot accessibility tree", () => session.send("Accessibility.getFullAXTree")));
 	}
 	let scopeApplied = false;
-	const filteredNodes = (await (async () => {
+	const nodesForOutline = await (async () => {
 		const locator = opts.focusLocator;
 		if (!locator) return nodes;
 		const sel = locator.selector.trim();
 		if (!sel) return nodes;
+		let objectId = null;
 		try {
 			const looksLikeXPath = /^xpath=/i.test(sel) || sel.startsWith("/");
 			const nth = locator.nth ?? 0;
-			const objectId = looksLikeXPath ? await resolveObjectIdForXPath(session, sel, frameId, nth) : await resolveObjectIdForCss(session, sel, frameId, nth);
+			objectId = looksLikeXPath ? await resolveObjectIdForXPath(session, sel, frameId, nth, progress) : await resolveObjectIdForCss(session, sel, frameId, nth, progress);
 			if (!objectId) return nodes;
-			const be = (await session.send("DOM.describeNode", { objectId })).node?.backendNodeId;
+			const be = (await runLocatorStep(progress, "reading snapshot focus", () => session.send("DOM.describeNode", { objectId }))).node?.backendNodeId;
 			if (typeof be !== "number") return nodes;
 			const target = nodes.find((n) => n.backendDOMNodeId === be);
 			if (!target) return nodes;
@@ -17352,9 +17367,14 @@ async function a11yForFrame(session, frameId, opts) {
 				parentId: void 0
 			} : n);
 		} catch {
+			progress?.throwIfStopped();
 			return nodes;
+		} finally {
+			await releaseSnapshotObject(session, objectId ?? void 0, progress);
 		}
-	})()).filter((node) => {
+	})();
+	progress?.throwIfStopped();
+	const filteredNodes = nodesForOutline.filter((node) => {
 		const be = node.backendDOMNodeId;
 		return typeof be !== "number" || !opts.isIgnoredBackendNode?.(be);
 	});
@@ -17368,6 +17388,7 @@ async function a11yForFrame(session, frameId, opts) {
 		urlMap[enc] = url;
 	}
 	const { tree } = await buildHierarchicalTree(decorateRoles(filteredNodes, opts), opts);
+	progress?.throwIfStopped();
 	return {
 		outline: tree.map((n) => formatTreeLine(n)).join("\n").trimEnd(),
 		urlMap,
@@ -17529,11 +17550,12 @@ function collectDomTraversalTargets(node) {
 * Rehydrate a truncated DOM tree by repeatedly calling DOM.describeNode with
 * decreasing depths. Any non-CBOR failure is surfaced directly.
 */
-async function hydrateDomTree(session, root, pierce) {
+async function hydrateDomTree(session, root, pierce, progress) {
 	const stack = [root];
 	const expandedNodeIds = /* @__PURE__ */ new Set();
 	const expandedBackendIds = /* @__PURE__ */ new Set();
 	while (stack.length) {
+		progress?.throwIfStopped();
 		const node = stack.pop();
 		const nodeId = typeof node.nodeId === "number" && node.nodeId > 0 ? node.nodeId : void 0;
 		const backendId = typeof node.backendNodeId === "number" && node.backendNodeId > 0 ? node.backendNodeId : void 0;
@@ -17547,11 +17569,11 @@ async function hydrateDomTree(session, root, pierce) {
 			let expanded = false;
 			let lastRetryError;
 			for (const depth of DESCRIBE_DEPTH_ATTEMPTS) try {
-				const described = await session.send("DOM.describeNode", {
+				const described = await runLocatorStep(progress, "expanding snapshot DOM", () => session.send("DOM.describeNode", {
 					...describeParamsBase,
 					depth,
 					pierce
-				});
+				}));
 				mergeDomNodes(node, described.node);
 				if (!nodeId && described.node.nodeId && described.node.nodeId > 0) {
 					node.nodeId = described.node.nodeId;
@@ -17560,6 +17582,7 @@ async function hydrateDomTree(session, root, pierce) {
 				expanded = true;
 				break;
 			} catch (err) {
+				progress?.throwIfStopped();
 				if (isCborStackError(err instanceof Error ? err.message : String(err))) {
 					lastRetryError = err;
 					continue;
@@ -17579,16 +17602,17 @@ async function hydrateDomTree(session, root, pierce) {
 * complaining. When a shallower snapshot is returned we hydrate the missing
 * branches so downstream DOM traversals see the full tree shape.
 */
-async function getDomTreeWithFallback(session, pierce) {
+async function getDomTreeWithFallback(session, pierce, progress) {
 	let lastRetryError;
 	for (const depth of DOM_DEPTH_ATTEMPTS) try {
-		const { root } = await session.send("DOM.getDocument", {
+		const { root } = await runLocatorStep(progress, "reading snapshot DOM", () => session.send("DOM.getDocument", {
 			depth,
 			pierce
-		});
-		if (depth !== -1) await hydrateDomTree(session, root, pierce);
+		}));
+		if (depth !== -1) await hydrateDomTree(session, root, pierce, progress);
 		return root;
 	} catch (err) {
+		progress?.throwIfStopped();
 		if (isCborStackError(err instanceof Error ? err.message : String(err))) {
 			lastRetryError = err;
 			continue;
@@ -17602,17 +17626,19 @@ async function getDomTreeWithFallback(session, pierce) {
 * Build tag name and XPath maps for a single frame session.
 * EncodedId is produced by a frame-aware encoder provided by the caller.
 */
-async function domMapsForSession(session, frameId, pierce, encode, attemptOwnerLookup = true) {
-	await session.send("DOM.enable").catch(() => {});
-	const root = await getDomTreeWithFallback(session, pierce);
+async function domMapsForSession(session, frameId, pierce, encode, attemptOwnerLookup = true, progress) {
+	await runLocatorStep(progress, "enabling DOM", () => session.send("DOM.enable").catch(() => {}));
+	const root = await getDomTreeWithFallback(session, pierce, progress);
 	let startNode = root;
 	if (attemptOwnerLookup) try {
-		const ownerBackendId = (await session.send("DOM.getFrameOwner", { frameId })).backendNodeId;
+		const ownerBackendId = (await runLocatorStep(progress, "finding snapshot iframe owner", () => session.send("DOM.getFrameOwner", { frameId }))).backendNodeId;
 		if (typeof ownerBackendId === "number") {
 			const ownerEl = findNodeByBackendId(root, ownerBackendId);
 			if (ownerEl?.contentDocument) startNode = ownerEl.contentDocument;
 		}
-	} catch {}
+	} catch {
+		progress?.throwIfStopped();
+	}
 	const tagNameMap = {};
 	const xpathMap = {};
 	const scrollableMap = {};
@@ -17621,6 +17647,7 @@ async function domMapsForSession(session, frameId, pierce, encode, attemptOwnerL
 		xpath: ""
 	}];
 	while (stack.length) {
+		progress?.throwIfStopped();
 		const { node, xpath } = stack.pop();
 		if (node.backendNodeId) {
 			const encId = encode(frameId, node.backendNodeId);
@@ -17645,6 +17672,7 @@ async function domMapsForSession(session, frameId, pierce, encode, attemptOwnerL
 			xpath: joinXPath(xpath, "//")
 		});
 	}
+	progress?.throwIfStopped();
 	return {
 		tagNameMap,
 		xpathMap,
@@ -17656,9 +17684,9 @@ async function domMapsForSession(session, frameId, pierce, encode, attemptOwnerL
 * Once the index is cached, per-frame slices are derived without extra DOM
 * calls, which keeps snapshot capture linear in the number of frames.
 */
-async function buildSessionDomIndex(session, pierce) {
-	await session.send("DOM.enable").catch(() => {});
-	const root = await getDomTreeWithFallback(session, true);
+async function buildSessionDomIndex(session, pierce, progress) {
+	await runLocatorStep(progress, "enabling DOM", () => session.send("DOM.enable").catch(() => {}));
+	const root = await getDomTreeWithFallback(session, true, progress);
 	const absByBe = /* @__PURE__ */ new Map();
 	const tagByBe = /* @__PURE__ */ new Map();
 	const scrollByBe = /* @__PURE__ */ new Map();
@@ -17675,6 +17703,7 @@ async function buildSessionDomIndex(session, pierce) {
 	}];
 	let dfsIndex = 0;
 	while (stack.length) {
+		progress?.throwIfStopped();
 		const { node, xp, docRootBe, phase } = stack.pop();
 		if (phase === "exit") {
 			if (node.backendNodeId) exitByBe.set(node.backendNodeId, dfsIndex++);
@@ -17724,6 +17753,7 @@ async function buildSessionDomIndex(session, pierce) {
 			});
 		}
 	}
+	progress?.throwIfStopped();
 	return {
 		rootBackend: rootBe,
 		absByBe,
@@ -17820,7 +17850,8 @@ var toWellFormed = (value) => value.toWellFormed();
 *
 * Each numbered block below references the step above for easier debugging.
 */
-async function captureHybridSnapshot(page, options, logger = page.logger) {
+async function captureHybridSnapshot(page, options, progress, logger = page.logger) {
+	progress.throwIfStopped();
 	const pierce = options?.pierceShadow ?? true;
 	const includeIframes = options?.includeIframes !== false;
 	const hasIgnoreLocators = (options?.ignoreLocators?.length ?? 0) > 0;
@@ -17828,17 +17859,18 @@ async function captureHybridSnapshot(page, options, logger = page.logger) {
 	const framesInScope = includeIframes ? [...context.frames] : [context.rootId];
 	if (!framesInScope.includes(context.rootId)) framesInScope.unshift(context.rootId);
 	if (!hasIgnoreLocators) {
-		const scopedSnapshot = await tryScopedSnapshot(page, options, context, pierce, /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), logger);
+		const scopedSnapshot = await tryScopedSnapshot(page, options, context, pierce, /* @__PURE__ */ new Map(), /* @__PURE__ */ new Map(), logger, progress);
 		if (scopedSnapshot) return scopedSnapshot;
 	}
-	const sessionToIndex = await buildSessionIndexes(page, framesInScope, pierce);
-	const exclusionIntervalsByFrame = await buildFrameExclusionIntervals(page, context, sessionToIndex, await resolveIgnoredNodes(page, options?.ignoreLocators, context, sessionToIndex));
+	const sessionToIndex = await buildSessionIndexes(page, framesInScope, pierce, progress);
+	const exclusionIntervalsByFrame = await buildFrameExclusionIntervals(page, context, sessionToIndex, await resolveIgnoredNodes(page, options?.ignoreLocators, context, sessionToIndex, progress), progress);
 	if (hasIgnoreLocators) {
-		const scopedSnapshot = await tryScopedSnapshot(page, options, context, pierce, sessionToIndex, exclusionIntervalsByFrame, logger);
+		const scopedSnapshot = await tryScopedSnapshot(page, options, context, pierce, sessionToIndex, exclusionIntervalsByFrame, logger, progress);
 		if (scopedSnapshot) return scopedSnapshot;
 	}
-	const { perFrameMaps, perFrameOutlines } = await collectPerFrameMaps(page, context, sessionToIndex, options, pierce, framesInScope, exclusionIntervalsByFrame);
-	const { absPrefix, iframeHostEncByChild } = await computeFramePrefixes(page, context, perFrameMaps, framesInScope);
+	const { perFrameMaps, perFrameOutlines } = await collectPerFrameMaps(page, context, sessionToIndex, options, pierce, framesInScope, exclusionIntervalsByFrame, progress);
+	const { absPrefix, iframeHostEncByChild } = await computeFramePrefixes(page, context, perFrameMaps, framesInScope, progress);
+	progress.throwIfStopped();
 	return mergeFramesIntoSnapshot(context, perFrameMaps, perFrameOutlines, absPrefix, iframeHostEncByChild, framesInScope);
 }
 /**
@@ -17869,7 +17901,8 @@ function buildFrameContext(page) {
 * Returns `null` when scoping fails (e.g., locator miss) so the caller can
 * fall back to the full multi-frame snapshot.
 */
-async function tryScopedSnapshot(page, options, context, pierce, sessionToIndex, exclusionIntervalsByFrame, logger) {
+async function tryScopedSnapshot(page, options, context, pierce, sessionToIndex, exclusionIntervalsByFrame, logger, progress) {
+	progress?.throwIfStopped();
 	const focusLocator = options?.focusLocator;
 	if (!focusLocator) return null;
 	const requestedFocus = focusLocator.selector.trim();
@@ -17883,12 +17916,12 @@ async function tryScopedSnapshot(page, options, context, pierce, sessionToIndex,
 		let tailSelector;
 		let absPrefix;
 		if (/^xpath=/i.test(requestedFocus) || requestedFocus.startsWith("/")) {
-			const hit = await resolveFocusFrameAndTail(page, normalizeXPath(requestedFocus), context.parentByFrame, context.rootId);
+			const hit = await resolveFocusFrameAndTail(page, normalizeXPath(requestedFocus), context.parentByFrame, context.rootId, progress);
 			targetFrameId = hit.targetFrameId;
 			tailSelector = hit.tailXPath || void 0;
 			absPrefix = hit.absPrefix;
 		} else {
-			const cssHit = await resolveCssFocusFrameAndTail(page, requestedFocus, context.parentByFrame, context.rootId);
+			const cssHit = await resolveCssFocusFrameAndTail(page, requestedFocus, context.parentByFrame, context.rootId, progress);
 			targetFrameId = cssHit.targetFrameId;
 			tailSelector = cssHit.tailSelector || void 0;
 			absPrefix = cssHit.absPrefix;
@@ -17896,7 +17929,7 @@ async function tryScopedSnapshot(page, options, context, pierce, sessionToIndex,
 		const owningSess = ownerSession(page, targetFrameId);
 		const parentId = context.parentByFrame.get(targetFrameId);
 		const sameSessionAsParent = !!parentId && ownerSession(page, parentId) === ownerSession(page, targetFrameId);
-		const { tagNameMap, xpathMap, scrollableMap } = await domMapsForSession(owningSess, targetFrameId, pierce, (fid, be) => `${page.getOrdinal(fid)}-${be}`, sameSessionAsParent);
+		const { tagNameMap, xpathMap, scrollableMap } = await domMapsForSession(owningSess, targetFrameId, pierce, (fid, be) => `${page.getOrdinal(fid)}-${be}`, sameSessionAsParent, progress);
 		const { outline, urlMap, scopeApplied } = await a11yForFrame(owningSess, targetFrameId, {
 			focusLocator: tailSelector ? {
 				selector: tailSelector,
@@ -17906,7 +17939,7 @@ async function tryScopedSnapshot(page, options, context, pierce, sessionToIndex,
 			tagNameMap,
 			scrollableMap,
 			encode: (backendNodeId) => `${page.getOrdinal(targetFrameId)}-${backendNodeId}`
-		});
+		}, progress);
 		const scopedXpathMap = {};
 		const isIgnoredBackendNode = makeIsIgnoredBackendNode(targetFrameId, ownerSessionIndexForFrame(page, targetFrameId, sessionToIndex), exclusionIntervalsByFrame);
 		const abs = absPrefix ?? "";
@@ -17936,6 +17969,7 @@ async function tryScopedSnapshot(page, options, context, pierce, sessionToIndex,
 		if (scopeApplied) return snapshot;
 		logScopeFallback();
 	} catch {
+		progress?.throwIfStopped();
 		logScopeFallback();
 	}
 	return null;
@@ -17945,16 +17979,18 @@ async function tryScopedSnapshot(page, options, context, pierce, sessionToIndex,
 * result so per-frame slices can share the structure. We key by session id
 * because same process iframes live inside the same session.
 */
-async function buildSessionIndexes(page, frames, pierce) {
+async function buildSessionIndexes(page, frames, pierce, progress) {
 	const sessionToIndex = /* @__PURE__ */ new Map();
 	const sessionById = /* @__PURE__ */ new Map();
 	for (const frameId of frames) {
+		progress?.throwIfStopped();
 		const sess = ownerSession(page, frameId);
 		const sid = sess.id ?? "root";
 		if (!sessionById.has(sid)) sessionById.set(sid, sess);
 	}
 	for (const [sid, sess] of sessionById.entries()) {
-		const idx = await buildSessionDomIndex(sess, pierce);
+		progress?.throwIfStopped();
+		const idx = await buildSessionDomIndex(sess, pierce, progress);
 		sessionToIndex.set(sid, idx);
 	}
 	return sessionToIndex;
@@ -17967,20 +18003,21 @@ async function buildSessionIndexes(page, frames, pierce) {
 *  - collects tag/xpath/scrollability maps for DOM-based lookups
 *  - fetches its AX tree to produce outlines and URL maps
 */
-async function collectPerFrameMaps(page, context, sessionToIndex, options, pierce, frameIds, exclusionIntervalsByFrame) {
+async function collectPerFrameMaps(page, context, sessionToIndex, options, pierce, frameIds, exclusionIntervalsByFrame, progress) {
 	const perFrameMaps = /* @__PURE__ */ new Map();
 	const perFrameOutlines = [];
 	for (const frameId of frameIds) {
+		progress?.throwIfStopped();
 		const sess = ownerSession(page, frameId);
 		const sid = sess.id ?? "root";
 		let idx = sessionToIndex.get(sid);
 		if (!idx) {
-			idx = await buildSessionDomIndex(sess, pierce);
+			idx = await buildSessionDomIndex(sess, pierce, progress);
 			sessionToIndex.set(sid, idx);
 		}
 		const parentId = context.parentByFrame.get(frameId);
 		const sameSessionAsParent = !!parentId && ownerSession(page, parentId) === sess;
-		const docRootBe = await resolveFrameDocRootBackendId(page, frameId, idx, sameSessionAsParent);
+		const docRootBe = await resolveFrameDocRootBackendId(page, frameId, idx, sameSessionAsParent, progress);
 		if (docRootBe === void 0) continue;
 		const tagNameMap = {};
 		const xpathMap = {};
@@ -18004,7 +18041,7 @@ async function collectPerFrameMaps(page, context, sessionToIndex, options, pierc
 			tagNameMap,
 			scrollableMap,
 			encode: (backendNodeId) => `${page.getOrdinal(frameId)}-${backendNodeId}`
-		});
+		}, progress);
 		perFrameOutlines.push({
 			frameId,
 			outline
@@ -18021,38 +18058,40 @@ async function collectPerFrameMaps(page, context, sessionToIndex, options, pierc
 		perFrameOutlines
 	};
 }
-async function resolveIgnoredNodes(page, ignoreLocators, context, sessionToIndex) {
+async function resolveIgnoredNodes(page, ignoreLocators, context, sessionToIndex, progress) {
 	const ignoredNodesByFrame = /* @__PURE__ */ new Map();
 	for (const locator of ignoreLocators ?? []) {
+		progress?.throwIfStopped();
 		const selector = locator.selector.trim();
 		if (!selector) continue;
 		try {
 			const resolved = await resolveIgnoredNodesForLocator(page, {
 				...locator,
 				selector
-			}, context, sessionToIndex);
+			}, context, sessionToIndex, progress);
 			for (const match of resolved) {
 				const nodes = ignoredNodesByFrame.get(match.frameId) ?? /* @__PURE__ */ new Set();
 				nodes.add(match.backendNodeId);
 				ignoredNodesByFrame.set(match.frameId, nodes);
 			}
 		} catch {
+			progress?.throwIfStopped();
 			continue;
 		}
 	}
 	return ignoredNodesByFrame;
 }
-async function resolveIgnoredNodesForLocator(page, locator, context, sessionToIndex) {
+async function resolveIgnoredNodesForLocator(page, locator, context, sessionToIndex, progress) {
 	const selector = locator.selector;
 	if (/^xpath=/i.test(selector) || selector.startsWith("/")) {
-		const hit = await resolveFocusFrameAndTail(page, normalizeXPath(selector), context.parentByFrame, context.rootId);
+		const hit = await resolveFocusFrameAndTail(page, normalizeXPath(selector), context.parentByFrame, context.rootId, progress);
 		const targetFrameId = hit.targetFrameId;
 		const tailXPath = hit.tailXPath || "/";
 		if (tailXPath === "/") {
 			const idx = ownerSessionIndexForFrame(page, targetFrameId, sessionToIndex);
 			if (!idx) return [];
 			const parentId = context.parentByFrame.get(targetFrameId);
-			const backendNodeId = await resolveFrameDocRootBackendId(page, targetFrameId, idx, !!parentId && ownerSession(page, parentId) === ownerSession(page, targetFrameId));
+			const backendNodeId = await resolveFrameDocRootBackendId(page, targetFrameId, idx, !!parentId && ownerSession(page, parentId) === ownerSession(page, targetFrameId), progress);
 			if (backendNodeId === void 0) return [];
 			return [{
 				frameId: targetFrameId,
@@ -18062,41 +18101,44 @@ async function resolveIgnoredNodesForLocator(page, locator, context, sessionToIn
 		return resolveIgnoredNodesInFrame(page, targetFrameId, {
 			kind: "xpath",
 			value: tailXPath
-		}, locator.nth);
+		}, locator.nth, progress);
 	}
-	const hit = await resolveCssFocusFrameAndTail(page, selector, context.parentByFrame, context.rootId);
+	const hit = await resolveCssFocusFrameAndTail(page, selector, context.parentByFrame, context.rootId, progress);
 	const targetFrameId = hit.targetFrameId;
 	return resolveIgnoredNodesInFrame(page, targetFrameId, {
 		kind: "css",
 		value: hit.tailSelector || selector
-	}, locator.nth);
+	}, locator.nth, progress);
 }
-async function resolveIgnoredNodesInFrame(page, frameId, query, nth) {
+async function resolveIgnoredNodesInFrame(page, frameId, query, nth, progress) {
 	const session = ownerSession(page, frameId);
-	const resolver = new FrameSelectorResolver(new Frame(session, frameId, "", false, page.logger));
-	const resolvedNodes = nth === void 0 ? await resolver.resolveAll(query) : [await resolver.resolveAtIndex(query, nth)].filter((node) => !!node);
+	const resolver = new FrameSelectorResolver(new Frame(session, frameId, "", false, page.logger), { readinessRetries: "none" });
+	const resolvedNodes = nth === void 0 ? await resolver.resolveAll(query, {}, progress) : [await resolver.resolveAtIndex(query, nth, progress)].filter((node) => !!node);
 	if (!resolvedNodes.length) return [];
-	return (await describeResolvedNodes(session, resolvedNodes)).map((backendNodeId) => ({
+	return (await describeResolvedNodes(session, resolvedNodes, progress)).map((backendNodeId) => ({
 		frameId,
 		backendNodeId
 	}));
 }
-async function describeResolvedNodes(session, resolvedNodes) {
+async function describeResolvedNodes(session, resolvedNodes, progress) {
 	const backendNodeIds = /* @__PURE__ */ new Set();
 	try {
 		for (const resolvedNode of resolvedNodes) {
-			const backendNodeId = (await session.send("DOM.describeNode", { objectId: resolvedNode.objectId })).node.backendNodeId;
+			const backendNodeId = (await runLocatorStep(progress, "reading ignored snapshot nodes", () => session.send("DOM.describeNode", { objectId: resolvedNode.objectId }))).node.backendNodeId;
 			if (typeof backendNodeId === "number") backendNodeIds.add(backendNodeId);
 		}
 	} finally {
-		await Promise.all(resolvedNodes.map((resolvedNode) => session.send("Runtime.releaseObject", { objectId: resolvedNode.objectId }).catch(() => {})));
+		const release = () => Promise.all(resolvedNodes.map((resolvedNode) => session.send("Runtime.releaseObject", { objectId: resolvedNode.objectId }).catch(() => {})));
+		if (progress) await progress.cleanup(release);
+		else await release();
 	}
+	progress?.throwIfStopped();
 	return [...backendNodeIds];
 }
-async function buildFrameExclusionIntervals(page, context, sessionToIndex, ignoredNodesByFrame) {
+async function buildFrameExclusionIntervals(page, context, sessionToIndex, ignoredNodesByFrame, progress) {
 	const intervalsByFrame = /* @__PURE__ */ new Map();
 	if (!ignoredNodesByFrame.size) return intervalsByFrame;
-	const childFramesByParent = await resolveChildFramesByParent(page, context);
+	const childFramesByParent = await resolveChildFramesByParent(page, context, progress);
 	const excludedFrames = /* @__PURE__ */ new Set();
 	const pushInterval = (frameId, start, end) => {
 		const intervals = intervalsByFrame.get(frameId) ?? [];
@@ -18107,12 +18149,13 @@ async function buildFrameExclusionIntervals(page, context, sessionToIndex, ignor
 		intervalsByFrame.set(frameId, intervals);
 	};
 	const excludeFrameSubtree = async (frameId) => {
+		progress?.throwIfStopped();
 		if (excludedFrames.has(frameId)) return;
 		excludedFrames.add(frameId);
 		const idx = ownerSessionIndexForFrame(page, frameId, sessionToIndex);
 		if (!idx) return;
 		const parentId = context.parentByFrame.get(frameId);
-		const docRootBe = await resolveFrameDocRootBackendId(page, frameId, idx, !!parentId && ownerSession(page, parentId) === ownerSession(page, frameId));
+		const docRootBe = await resolveFrameDocRootBackendId(page, frameId, idx, !!parentId && ownerSession(page, parentId) === ownerSession(page, frameId), progress);
 		if (docRootBe !== void 0) {
 			const start = idx.enterByBe.get(docRootBe);
 			const end = idx.exitByBe.get(docRootBe);
@@ -18121,6 +18164,7 @@ async function buildFrameExclusionIntervals(page, context, sessionToIndex, ignor
 		for (const childFrameId of listChildrenOf(context.parentByFrame, frameId)) await excludeFrameSubtree(childFrameId);
 	};
 	const excludeIgnoredNode = async (frameId, backendNodeId) => {
+		progress?.throwIfStopped();
 		const idx = ownerSessionIndexForFrame(page, frameId, sessionToIndex);
 		if (!idx) return;
 		const start = idx.enterByBe.get(backendNodeId);
@@ -18150,15 +18194,16 @@ async function buildFrameExclusionIntervals(page, context, sessionToIndex, ignor
 	}
 	return intervalsByFrame;
 }
-async function resolveChildFramesByParent(page, context) {
+async function resolveChildFramesByParent(page, context, progress) {
 	const childFramesByParent = /* @__PURE__ */ new Map();
 	for (const frameId of context.frames) {
+		progress?.throwIfStopped();
 		const parentId = context.parentByFrame.get(frameId);
 		if (!parentId) continue;
 		const session = parentSession(page, context.parentByFrame, frameId);
 		if (!session) continue;
 		try {
-			const { backendNodeId } = await session.send("DOM.getFrameOwner", { frameId });
+			const { backendNodeId } = await runLocatorStep(progress, "finding snapshot iframe owner", () => session.send("DOM.getFrameOwner", { frameId }));
 			if (typeof backendNodeId !== "number") continue;
 			const childFrames = childFramesByParent.get(parentId) ?? [];
 			childFrames.push({
@@ -18167,6 +18212,7 @@ async function resolveChildFramesByParent(page, context) {
 			});
 			childFramesByParent.set(parentId, childFrames);
 		} catch {
+			progress?.throwIfStopped();
 			continue;
 		}
 	}
@@ -18201,23 +18247,26 @@ function ownerSessionIndexForFrame(page, frameId, sessionToIndex) {
 	const session = ownerSession(page, frameId);
 	return sessionToIndex.get(session.id ?? "root");
 }
-async function resolveFrameDocRootBackendId(page, frameId, idx, sameSessionAsParent) {
+async function resolveFrameDocRootBackendId(page, frameId, idx, sameSessionAsParent, progress) {
+	progress?.throwIfStopped();
 	if (!sameSessionAsParent) return idx.rootBackend;
 	const session = ownerSession(page, frameId);
 	try {
-		const { backendNodeId } = await session.send("DOM.getFrameOwner", { frameId });
+		const { backendNodeId } = await runLocatorStep(progress, "finding snapshot iframe owner", () => session.send("DOM.getFrameOwner", { frameId }));
 		if (typeof backendNodeId === "number") {
 			const docRootBe = idx.contentDocRootByIframe.get(backendNodeId);
 			if (typeof docRootBe === "number") return docRootBe;
 		}
-	} catch {}
+	} catch {
+		progress?.throwIfStopped();
+	}
 }
 /**
 * Step 4 – walk the frame tree (parent-first) to compute absolute prefixes for
 * every frame. The prefix is the absolute XPath of the iframe element hosting
 * the frame, so we can later convert relative XPaths into cross-frame ones.
 */
-async function computeFramePrefixes(page, context, perFrameMaps, frameIds) {
+async function computeFramePrefixes(page, context, perFrameMaps, frameIds, progress) {
 	const absPrefix = /* @__PURE__ */ new Map();
 	const iframeHostEncByChild = /* @__PURE__ */ new Map();
 	absPrefix.set(context.rootId, "");
@@ -18225,6 +18274,7 @@ async function computeFramePrefixes(page, context, perFrameMaps, frameIds) {
 	const queue = [];
 	if (included.has(context.rootId)) queue.push(context.rootId);
 	while (queue.length) {
+		progress?.throwIfStopped();
 		const parent = queue.shift();
 		const parentAbs = absPrefix.get(parent);
 		for (const child of context.frames) {
@@ -18234,9 +18284,10 @@ async function computeFramePrefixes(page, context, perFrameMaps, frameIds) {
 			const parentSess = parentSession(page, context.parentByFrame, child);
 			const ownerBackendNodeId = await (async () => {
 				try {
-					const { backendNodeId } = await parentSess.send("DOM.getFrameOwner", { frameId: child });
+					const { backendNodeId } = await runLocatorStep(progress, "finding snapshot iframe owner", () => parentSess.send("DOM.getFrameOwner", { frameId: child }));
 					return backendNodeId;
 				} catch {
+					progress?.throwIfStopped();
 					return;
 				}
 			})();
@@ -54319,7 +54370,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.1.0-alpha-c88a64f8d48d13e5e4d43d14fd9e54e388de3383",
+	version: "1.1.0-alpha-666b6fa32b003420a4a9e641dc47ee4c9a531eff",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -57623,19 +57674,27 @@ var Page = class Page {
 			throw error;
 		}
 	}
-	async captureSnapshot(options) {
-		return await captureHybridSnapshot(this, options, this.logger);
+	async captureSnapshot(options, parentProgress) {
+		return await runWithProgress(parentProgress ?? {
+			name: "snapshot",
+			timeout: 0
+		}, (progress) => captureHybridSnapshot(this, options, progress, this.logger));
 	}
-	async snapshot(options) {
-		const { combinedTree, combinedXpathMap, combinedUrlMap } = await this.captureSnapshot({
-			pierceShadow: true,
-			includeIframes: options?.includeIframes
+	async snapshot(options, parentProgress) {
+		return await runWithProgress(parentProgress ?? {
+			name: "snapshot",
+			timeout: options?.timeout ?? 2e4
+		}, async (progress) => {
+			const { combinedTree, combinedXpathMap, combinedUrlMap } = await this.captureSnapshot({
+				pierceShadow: true,
+				includeIframes: options?.includeIframes
+			}, progress);
+			return {
+				formattedTree: combinedTree,
+				xpathMap: combinedXpathMap,
+				urlMap: combinedUrlMap
+			};
 		});
-		return {
-			formattedTree: combinedTree,
-			xpathMap: combinedXpathMap,
-			urlMap: combinedUrlMap
-		};
 	}
 	/** Press a key down without releasing it */
 	async keyDown(key) {

{stagehand-4.2.0a0.dev1560 → stagehand-4.2.0a0.dev1562}/src/stagehand/_generated/input_types.py

@@ -916,6 +916,7 @@ class PageSetViewportSizeParams(TypedDict):
 
 
 class PageSnapshotOptions(TypedDict):
+    timeout: NotRequired[float]
     include_iframes: NotRequired[bool]
 
 

{stagehand-4.2.0a0.dev1560 → stagehand-4.2.0a0.dev1562}/src/stagehand/_generated/models.py

@@ -1899,6 +1899,8 @@ class PageSnapshotOptions(WireModel):
         extra="forbid",
         validate_by_name=True,
     )
+    timeout: Annotated[Optional[StrictFloat], Field(ge=0.0)] = None
+    """Milliseconds for the whole snapshot call. Defaults to 20000. Zero disables the timeout."""
     include_iframes: Optional[StrictBool] = None
 
 

{stagehand-4.2.0a0.dev1560 → stagehand-4.2.0a0.dev1562}/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-c88a64f8d48d13e5e4d43d14fd9e54e388de3383'
+STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-666b6fa32b003420a4a9e641dc47ee4c9a531eff'

{stagehand-4.2.0a0.dev1560 → stagehand-4.2.0a0.dev1562}/src/stagehand/page.py

@@ -665,10 +665,17 @@ class Page:
             Path(path).write_bytes(data)
         return data
 
-    async def snapshot(self, *, include_iframes: bool | None = None) -> SnapshotResult:
+    async def snapshot(
+        self, *, include_iframes: bool | None = None, timeout: float | None = None
+    ) -> SnapshotResult:
         params = PageSnapshotParams(page_id=self.page_id)
-        if include_iframes is not None:
-            params.options = PageSnapshotOptions(include_iframes=include_iframes)
+        options = PageSnapshotOptions.model_validate({
+            key: value
+            for key, value in {"include_iframes": include_iframes, "timeout": timeout}.items()
+            if value is not None
+        })
+        if options.model_fields_set:
+            params.options = options
         return await self._rpc_client.send("page.snapshot", params, SnapshotResult)
 
     async def tools(self, *, timeout: float | None = None) -> list[WebMCPTool]:

{stagehand-4.2.0a0.dev1560 → stagehand-4.2.0a0.dev1562}/src/stagehand/rpc_client.py

@@ -31,6 +31,7 @@ _DEFAULT_OPERATION_TIMEOUT_MS = {
     "page.wait_for_load_state": 15_000,
     "page.wait_for_selector": 30_000,
     "page.pdf": 30_000,
+    "page.snapshot": 20_000,
     "page.webmcp_tools": 1_000,
 }
 _UNBOUNDED_BY_DEFAULT_METHODS = {
@@ -56,7 +57,6 @@ _UNBOUNDED_BY_DEFAULT_METHODS = {
     "page.close",
     "page.evaluate",
     "page.screenshot",
-    "page.snapshot",
     "page.webmcp_invocation_result",
 }
 
@@ -557,6 +557,7 @@ def _rpc_response_timeout_seconds(method: str, params: BaseModel) -> float | Non
         "page.go_forward",
         "page.screenshot",
         "page.pdf",
+        "page.snapshot",
         "page.wait_for_selector",
         "page.webmcp_tools",
         "page.webmcp_invocation_result",
@@ -568,7 +569,7 @@ 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 == "page.pdf" and operation_timeout_ms == 0:
+        if method in {"page.pdf", "page.snapshot"} and operation_timeout_ms == 0:
             return None
         return (_RPC_RESPONSE_GRACE_MS + max(0, operation_timeout_ms)) / 1_000