stagehand 4.2.0a0.dev1556__tar.gz → 4.2.0a0.dev1558__tar.gz

{stagehand-4.2.0a0.dev1556 → stagehand-4.2.0a0.dev1558}/PKG-INFO

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

{stagehand-4.2.0a0.dev1556 → stagehand-4.2.0a0.dev1558}/pyproject.toml

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

{stagehand-4.2.0a0.dev1556 → stagehand-4.2.0a0.dev1558}/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-1562d3506204452eb76a4653fc4fabc4c7cc1e3e",
+	version: "2.1.0-alpha-173fe1ff6dae5dcadf512a16a41770e16f453330",
 	"private": true,
 	type: "module",
 	exports: {
@@ -15331,16 +15331,16 @@ var Locator = class Locator {
 	* Resolve all matching nodes for this locator.
 	* If the locator is narrowed via nth(), only that index is returned.
 	*/
-	async resolveNodesForMask() {
+	async resolveNodesForMask(progress) {
 		const session = this.frame.session;
-		await session.send("Runtime.enable");
-		await session.send("DOM.enable");
+		await progress.run("enabling runtime", () => session.send("Runtime.enable"));
+		await progress.run("enabling DOM", () => session.send("DOM.enable"));
 		if (this.nthIndex >= 0) {
-			const resolved = await this.selectorResolver.resolveAtIndex(this.selectorQuery, this.nthIndex);
+			const resolved = await this.selectorResolver.resolveAtIndex(this.selectorQuery, this.nthIndex, progress);
 			if (!resolved) throw new Error(`Could not find an element for the given xPath(s): ${this.selector}`);
 			return [resolved];
 		}
-		const resolved = await this.selectorResolver.resolveAll(this.selectorQuery);
+		const resolved = await this.selectorResolver.resolveAll(this.selectorQuery, {}, progress);
 		if (!resolved.length) throw new Error(`Could not find an element for the given xPath(s): ${this.selector}`);
 		return resolved;
 	}
@@ -16930,419 +16930,6 @@ async function act$1(params) {
 	};
 }
 //#endregion
-//#region dom/screenshotScripts/resolveMaskRect.ts
-function resolveMaskRect(maskToken) {
-	function safeClosest(el, selector) {
-		try {
-			return el && typeof el.closest === "function" ? el.closest(selector) : null;
-		} catch {
-			return null;
-		}
-	}
-	function safeMatches(el, selector) {
-		try {
-			return !!el && typeof el.matches === "function" && el.matches(selector);
-		} catch {
-			return false;
-		}
-	}
-	function findTopLayerRoot(el) {
-		const dialog = safeClosest(el, "dialog[open]");
-		if (dialog) return dialog;
-		const popover = safeClosest(el, "[popover]");
-		if (popover && safeMatches(popover, ":popover-open")) return popover;
-		return null;
-	}
-	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;
-	const root = findTopLayerRoot(this);
-	if (root) {
-		const rootRect = root.getBoundingClientRect();
-		const rootClientLeft = root.clientLeft || 0;
-		const rootClientTop = root.clientTop || 0;
-		const rootScrollLeft = root.scrollLeft || 0;
-		const rootScrollTop = root.scrollTop || 0;
-		let localRect = {
-			x: rect.left - rootRect.left - rootClientLeft + rootScrollLeft,
-			y: rect.top - rootRect.top - rootClientTop + rootScrollTop,
-			width: rect.width,
-			height: rect.height
-		};
-		try {
-			const rootElement = root;
-			const transformProperties = [
-				"transform",
-				"translate",
-				"rotate",
-				"scale"
-			];
-			const previous = transformProperties.map((property) => ({
-				property,
-				value: rootElement.style.getPropertyValue(property),
-				priority: rootElement.style.getPropertyPriority(property)
-			}));
-			const previousTransition = {
-				value: rootElement.style.getPropertyValue("transition"),
-				priority: rootElement.style.getPropertyPriority("transition")
-			};
-			const previousWillChange = {
-				value: rootElement.style.getPropertyValue("will-change"),
-				priority: rootElement.style.getPropertyPriority("will-change")
-			};
-			try {
-				rootElement.style.setProperty("transition", "none", "important");
-				rootElement.style.setProperty("will-change", "transform", "important");
-				root.getBoundingClientRect();
-				for (const property of transformProperties) rootElement.style.setProperty(property, "none", "important");
-				const untransformedRootRect = root.getBoundingClientRect();
-				const untransformedTargetRect = this.getBoundingClientRect();
-				if (untransformedTargetRect.width > 0 && untransformedTargetRect.height > 0 && Number.isFinite(untransformedRootRect.left) && Number.isFinite(untransformedRootRect.top)) {
-					const maskBleed = 3;
-					localRect = {
-						x: untransformedTargetRect.left - untransformedRootRect.left - rootClientLeft + rootScrollLeft - maskBleed,
-						y: untransformedTargetRect.top - untransformedRootRect.top - rootClientTop + rootScrollTop - maskBleed,
-						width: untransformedTargetRect.width + maskBleed * 2,
-						height: untransformedTargetRect.height + maskBleed * 2
-					};
-				}
-			} finally {
-				for (const { property, value, priority } of previous) if (value) rootElement.style.setProperty(property, value, priority);
-				else rootElement.style.removeProperty(property);
-				if (previousWillChange.value) rootElement.style.setProperty("will-change", previousWillChange.value, previousWillChange.priority);
-				else rootElement.style.removeProperty("will-change");
-				root.getBoundingClientRect();
-				if (previousTransition.value) rootElement.style.setProperty("transition", previousTransition.value, previousTransition.priority);
-				else rootElement.style.removeProperty("transition");
-			}
-		} catch {}
-		let rootToken = null;
-		if (maskToken) try {
-			const existing = root.getAttribute("data-stagehand-mask-root");
-			if (existing && existing.startsWith(maskToken)) rootToken = existing;
-			else {
-				rootToken = maskToken + "_root_" + Math.random().toString(36).slice(2);
-				root.setAttribute("data-stagehand-mask-root", rootToken);
-			}
-		} catch {
-			rootToken = null;
-		}
-		return {
-			...localRect,
-			rootToken,
-			position: style.position === "fixed" ? "fixed" : "absolute"
-		};
-	}
-	return {
-		x: rect.left + window.scrollX,
-		y: rect.top + window.scrollY,
-		width: rect.width,
-		height: rect.height,
-		rootToken: null
-	};
-}
-//#endregion
-//#region understudy/screenshotUtils.ts
-var screenshotQueues = /* @__PURE__ */ new WeakMap();
-/** Serialize page mutations, or the browser-wide activation/capture critical section. */
-async function withScreenshotLock(owner, capture, timeout, operation = "screenshot") {
-	const queue = screenshotQueues.get(owner) ?? {
-		tail: Promise.resolve(),
-		blocked: new AbortController()
-	};
-	queue.blocked.signal.throwIfAborted();
-	const controller = new AbortController();
-	let started = false;
-	const timer = typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0 ? setTimeout(() => {
-		const error = new TimeoutError(operation, timeout);
-		controller.abort(error);
-		if (started) queue.blocked.abort(new Error(`A previous capture is still recovering: ${error.message}`, { cause: error }));
-	}, Math.min(timeout, 2147483647)) : void 0;
-	const pending = queue.tail.then(() => {
-		queue.blocked.signal.throwIfAborted();
-		controller.signal.throwIfAborted();
-		started = true;
-		return capture(controller.signal);
-	});
-	const released = pending.then(() => {}, () => {});
-	queue.tail = released;
-	screenshotQueues.set(owner, queue);
-	try {
-		return await waitForScreenshot(waitForScreenshot(pending, queue.blocked.signal), controller.signal);
-	} finally {
-		if (timer !== void 0) clearTimeout(timer);
-		released.then(() => {
-			if (queue.tail === released) screenshotQueues.delete(owner);
-		});
-	}
-}
-/** Stop waiting for a stalled CDP capture; its eventual response cannot resume cleanup. */
-async function waitForScreenshot(pending, signal) {
-	if (!signal) return await pending;
-	return await new Promise((resolve, reject) => {
-		const onAbort = () => {
-			signal.removeEventListener("abort", onAbort);
-			reject(signal.reason);
-		};
-		if (signal.aborted) onAbort();
-		else signal.addEventListener("abort", onAbort, { once: true });
-		pending.then((value) => {
-			signal.removeEventListener("abort", onAbort);
-			resolve(value);
-		}, (error) => {
-			signal.removeEventListener("abort", onAbort);
-			reject(error);
-		});
-	});
-}
-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 RangeError(`screenshot: clip.${key} must be a finite number`);
-	if (width <= 0 || height <= 0) throw new RangeError("screenshot: clip width/height must be positive");
-	return {
-		x,
-		y,
-		width,
-		height
-	};
-}
-async function computeScreenshotScale(page, mode) {
-	if (mode !== "css") return void 0;
-	try {
-		const dpr = await page.mainFrame().evaluate(() => {
-			const ratio = Number(window.devicePixelRatio || 1);
-			return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
-		}).catch(() => 1);
-		return Math.min(2, Math.max(.1, 1 / (Number.isFinite(dpr) && dpr > 0 ? dpr : 1)));
-	} catch {
-		return 1;
-	}
-}
-async function setTransparentBackground(session) {
-	await session.send("Emulation.setDefaultBackgroundColorOverride", { color: {
-		r: 0,
-		g: 0,
-		b: 0,
-		a: 0
-	} }).catch(() => {});
-	return async () => {
-		await session.send("Emulation.setDefaultBackgroundColorOverride", {}).catch(() => {});
-	};
-}
-async function applyStyleToFrames(frames, css, label) {
-	const trimmed = css.trim();
-	if (!trimmed) return async () => {};
-	const token = `__v3_style_${label}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-	await Promise.all(frames.map((frame) => frame.evaluate(({ css, token }) => {
-		try {
-			const doc = document;
-			if (!doc) return;
-			const style = doc.createElement("style");
-			style.setAttribute("data-stagehand-style", token);
-			style.textContent = css;
-			(doc.head || doc.documentElement || doc.body)?.appendChild(style);
-		} catch {}
-	}, {
-		css: trimmed,
-		token
-	}).catch(() => {})));
-	return async () => {
-		await Promise.all(frames.map((frame) => frame.evaluate((token) => {
-			try {
-				const doc = document;
-				if (!doc) return;
-				doc.querySelectorAll(`[data-stagehand-style="${token}"]`).forEach((node) => node.remove());
-			} catch {}
-		}, token).catch(() => {})));
-	};
-}
-async function disableAnimations(frames) {
-	const cleanup = await applyStyleToFrames(frames, `
-*,
-*::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;
-}`, "animations");
-	await Promise.all(frames.map((frame) => frame.evaluate(() => {
-		try {
-			const animations = typeof document.getAnimations === "function" ? document.getAnimations() : [];
-			for (const animation of animations) try {
-				const details = animation.effect?.getComputedTiming?.();
-				if (details && details.iterations !== Infinity) animation.finish?.();
-				else animation.cancel?.();
-			} catch {
-				animation.cancel?.();
-			}
-		} catch {}
-	}).catch(() => {})));
-	return cleanup;
-}
-async function hideCaret(frames) {
-	return applyStyleToFrames(frames, `
-input,
-textarea,
-[contenteditable],
-[contenteditable=""],
-[contenteditable="true"],
-[contenteditable="plaintext-only"],
-*:focus {
-  caret-color: transparent !important;
-}`, "caret");
-}
-async function applyMaskOverlays(locators, color) {
-	const rectsByFrame = /* @__PURE__ */ new Map();
-	const token = `__v3_mask_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-	for (const locator of locators) try {
-		const info = await resolveMaskRects("real" in locator ? await locator.real() : locator, token);
-		if (!info) continue;
-		const entry = rectsByFrame.get(info.frame) ?? {
-			rects: [],
-			rootTokens: /* @__PURE__ */ new Set()
-		};
-		entry.rects.push(...info.rects);
-		for (const rect of info.rects) if (rect.rootToken) entry.rootTokens.add(rect.rootToken);
-		rectsByFrame.set(info.frame, entry);
-	} catch {}
-	if (rectsByFrame.size === 0) return async () => {};
-	await Promise.all(Array.from(rectsByFrame.entries()).map(([frame, { rects }]) => frame.evaluate(({ rects, color, token }) => {
-		try {
-			const doc = document;
-			if (!doc) return;
-			for (const rect of rects) {
-				const defaultRoot = doc.documentElement || doc.body;
-				if (!defaultRoot) return;
-				const root = rect.rootToken ? doc.querySelector(`[data-stagehand-mask-root="${rect.rootToken}"]`) || defaultRoot : defaultRoot;
-				if (!root) continue;
-				if (rect.rootToken) try {
-					const style = window.getComputedStyle(root);
-					if (style && style.position === "static") {
-						const rootEl = root;
-						if (!rootEl.hasAttribute("data-stagehand-mask-root-pos")) rootEl.setAttribute("data-stagehand-mask-root-pos", rootEl.style.position || "");
-						rootEl.style.position = "relative";
-					}
-				} catch {}
-				const el = doc.createElement("div");
-				el.setAttribute("data-stagehand-mask", token);
-				el.style.position = rect.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 = color;
-				el.style.pointerEvents = "none";
-				el.style.zIndex = "2147483647";
-				el.style.opacity = "1";
-				el.style.mixBlendMode = "normal";
-				root.appendChild(el);
-			}
-		} catch {}
-	}, {
-		rects,
-		color,
-		token
-	}).catch(() => {})));
-	await new Promise((resolve) => setTimeout(resolve, 100));
-	return async () => {
-		await Promise.all(Array.from(rectsByFrame.entries()).map(([frame, { rootTokens }]) => frame.evaluate(({ token, rootTokens }) => {
-			try {
-				const doc = document;
-				if (!doc) return;
-				doc.querySelectorAll(`[data-stagehand-mask="${token}"]`).forEach((node) => node.remove());
-				for (const rootToken of rootTokens) {
-					const root = doc.querySelector(`[data-stagehand-mask-root="${rootToken}"]`);
-					if (!root) continue;
-					const prev = root.getAttribute("data-stagehand-mask-root-pos");
-					if (prev !== null) {
-						root.style.position = prev;
-						root.removeAttribute("data-stagehand-mask-root-pos");
-					}
-					root.removeAttribute("data-stagehand-mask-root");
-				}
-			} catch {}
-		}, {
-			token,
-			rootTokens: Array.from(rootTokens)
-		}).catch(() => {})));
-	};
-}
-async function resolveMaskRects(locator, maskToken) {
-	const frame = locator.getFrame();
-	const session = frame.session;
-	try {
-		const resolved = await locator.resolveNodesForMask();
-		const rects = [];
-		for (const { objectId } of resolved) try {
-			const rect = await resolveMaskRectForObject(session, objectId, maskToken);
-			if (rect) rects.push(rect);
-		} catch {} finally {
-			await session.send("Runtime.releaseObject", { objectId }).catch(() => {});
-		}
-		if (!rects.length) return null;
-		return {
-			frame,
-			rects
-		};
-	} catch {
-		return null;
-	}
-}
-async function resolveMaskRectForObject(session, objectId, maskToken) {
-	const result = await session.send("Runtime.callFunctionOn", {
-		objectId,
-		functionDeclaration: resolveMaskRect.toString(),
-		arguments: [{ value: maskToken }],
-		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 {
-		x,
-		y,
-		width,
-		height,
-		rootToken: rect.rootToken && typeof rect.rootToken === "string" ? rect.rootToken : void 0,
-		position: rect.position === "fixed" ? "fixed" : "absolute"
-	};
-}
-async function runScreenshotCleanups(cleanups) {
-	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") await result;
-		} catch {}
-	}
-}
-//#endregion
 //#region understudy/frame.ts
 function base64ToBytes$1(base64) {
 	const binary = globalThis.atob(base64);
@@ -17422,10 +17009,13 @@ var Frame = class Frame {
 	* Evaluate a function or expression in this frame's main world.
 	* - If a string is provided, treated as a JS expression.
 	* - If a function is provided, it is stringified and invoked with the optional argument.
+	* Progress guards dispatch, but issued evaluations are awaited so screenshot
+	* restoration cannot run before a late page mutation finishes.
 	*/
-	async evaluate(pageFunctionOrExpression, arg) {
+	async evaluate(pageFunctionOrExpression, arg, progress) {
+		progress?.throwIfStopped();
 		await this.session.send("Runtime.enable").catch(() => {});
-		const contextId = await this.getMainWorldExecutionContextId();
+		const contextId = await this.getMainWorldExecutionContextId(progress);
 		const isString = typeof pageFunctionOrExpression === "string";
 		let expression;
 		if (isString) expression = String(pageFunctionOrExpression);
@@ -17441,6 +17031,7 @@ var Frame = class Frame {
       })()`;
 		let res;
 		try {
+			progress?.throwIfStopped();
 			res = await this.session.send("Runtime.evaluate", {
 				expression,
 				contextId,
@@ -17449,7 +17040,8 @@ var Frame = class Frame {
 			});
 		} catch (error) {
 			if (!(error instanceof Error ? error.message : String(error)).includes("Cannot find context with specified id")) throw error;
-			const freshContextId = await this.getMainWorldExecutionContextId();
+			const freshContextId = await this.getMainWorldExecutionContextId(progress);
+			progress?.throwIfStopped();
 			res = await this.session.send("Runtime.evaluate", {
 				expression,
 				contextId: freshContextId,
@@ -17490,10 +17082,9 @@ var Frame = class Frame {
 		return response.result.value;
 	}
 	/** Page.captureScreenshot (frame-scoped session) */
-	async screenshot(options) {
-		const signal = options?.signal;
-		signal?.throwIfAborted();
-		await waitForScreenshot(this.session.send("Page.enable"), signal);
+	async screenshot(options, progress) {
+		progress.throwIfStopped();
+		await this.session.send("Page.enable");
 		const format = options?.type ?? "png";
 		const params = {
 			format,
@@ -17514,8 +17105,11 @@ var Frame = class Frame {
 			const q = Math.round(options.quality);
 			params.quality = Math.min(100, Math.max(0, q));
 		}
-		await waitForScreenshot(this.session.send("Page.bringToFront"), signal);
-		const { data } = await waitForScreenshot(this.session.send("Page.captureScreenshot", params), signal);
+		progress.throwIfStopped();
+		await this.session.send("Page.bringToFront");
+		progress.throwIfStopped();
+		const { data } = await this.session.send("Page.captureScreenshot", params);
+		progress.throwIfStopped();
 		return base64ToBytes$1(data);
 	}
 	/** Child frames via Page.getFrameTree */
@@ -17566,8 +17160,8 @@ var Frame = class Frame {
 		return new Locator(this, selector, options);
 	}
 	/** Resolve the main-world execution context id for this frame. */
-	async getMainWorldExecutionContextId() {
-		return executionContexts.waitForMainWorld(this.session, this.frameId, 1e3);
+	async getMainWorldExecutionContextId(progress) {
+		return executionContexts.waitForMainWorld(this.session, this.frameId, 1e3, progress);
 	}
 	async getExtensionWorldExecutionContextId() {
 		return executionContexts.waitForExtensionWorld(this.session, this.frameId, 1e3);
@@ -54725,7 +54319,7 @@ var WebTracerProvider = class extends BasicTracerProvider {
 };
 var package_default = {
 	name: "@browserbasehq/stagehand-extension",
-	version: "1.1.0-alpha-1562d3506204452eb76a4653fc4fabc4c7cc1e3e",
+	version: "1.1.0-alpha-173fe1ff6dae5dcadf512a16a41770e16f453330",
 	"private": true,
 	type: "module",
 	scripts: {
@@ -56120,6 +55714,423 @@ async function normalizeInitScriptSource(script, arg, caller = DEFAULT_CALLER) {
 	throw new TypeError(`${caller}: provide a string, function, or an object with content.`);
 }
 //#endregion
+//#region dom/screenshotScripts/resolveMaskRect.ts
+function resolveMaskRect(maskToken) {
+	function safeClosest(el, selector) {
+		try {
+			return el && typeof el.closest === "function" ? el.closest(selector) : null;
+		} catch {
+			return null;
+		}
+	}
+	function safeMatches(el, selector) {
+		try {
+			return !!el && typeof el.matches === "function" && el.matches(selector);
+		} catch {
+			return false;
+		}
+	}
+	function findTopLayerRoot(el) {
+		const dialog = safeClosest(el, "dialog[open]");
+		if (dialog) return dialog;
+		const popover = safeClosest(el, "[popover]");
+		if (popover && safeMatches(popover, ":popover-open")) return popover;
+		return null;
+	}
+	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;
+	const root = findTopLayerRoot(this);
+	if (root) {
+		const rootRect = root.getBoundingClientRect();
+		const rootClientLeft = root.clientLeft || 0;
+		const rootClientTop = root.clientTop || 0;
+		const rootScrollLeft = root.scrollLeft || 0;
+		const rootScrollTop = root.scrollTop || 0;
+		let localRect = {
+			x: rect.left - rootRect.left - rootClientLeft + rootScrollLeft,
+			y: rect.top - rootRect.top - rootClientTop + rootScrollTop,
+			width: rect.width,
+			height: rect.height
+		};
+		try {
+			const rootElement = root;
+			const transformProperties = [
+				"transform",
+				"translate",
+				"rotate",
+				"scale"
+			];
+			const previous = transformProperties.map((property) => ({
+				property,
+				value: rootElement.style.getPropertyValue(property),
+				priority: rootElement.style.getPropertyPriority(property)
+			}));
+			const previousTransition = {
+				value: rootElement.style.getPropertyValue("transition"),
+				priority: rootElement.style.getPropertyPriority("transition")
+			};
+			const previousWillChange = {
+				value: rootElement.style.getPropertyValue("will-change"),
+				priority: rootElement.style.getPropertyPriority("will-change")
+			};
+			try {
+				rootElement.style.setProperty("transition", "none", "important");
+				rootElement.style.setProperty("will-change", "transform", "important");
+				root.getBoundingClientRect();
+				for (const property of transformProperties) rootElement.style.setProperty(property, "none", "important");
+				const untransformedRootRect = root.getBoundingClientRect();
+				const untransformedTargetRect = this.getBoundingClientRect();
+				if (untransformedTargetRect.width > 0 && untransformedTargetRect.height > 0 && Number.isFinite(untransformedRootRect.left) && Number.isFinite(untransformedRootRect.top)) {
+					const maskBleed = 3;
+					localRect = {
+						x: untransformedTargetRect.left - untransformedRootRect.left - rootClientLeft + rootScrollLeft - maskBleed,
+						y: untransformedTargetRect.top - untransformedRootRect.top - rootClientTop + rootScrollTop - maskBleed,
+						width: untransformedTargetRect.width + maskBleed * 2,
+						height: untransformedTargetRect.height + maskBleed * 2
+					};
+				}
+			} finally {
+				for (const { property, value, priority } of previous) if (value) rootElement.style.setProperty(property, value, priority);
+				else rootElement.style.removeProperty(property);
+				if (previousWillChange.value) rootElement.style.setProperty("will-change", previousWillChange.value, previousWillChange.priority);
+				else rootElement.style.removeProperty("will-change");
+				root.getBoundingClientRect();
+				if (previousTransition.value) rootElement.style.setProperty("transition", previousTransition.value, previousTransition.priority);
+				else rootElement.style.removeProperty("transition");
+			}
+		} catch {}
+		let rootToken = null;
+		if (maskToken) try {
+			const existing = root.getAttribute("data-stagehand-mask-root");
+			if (existing && existing.startsWith(maskToken)) rootToken = existing;
+			else {
+				rootToken = maskToken + "_root_" + Math.random().toString(36).slice(2);
+				root.setAttribute("data-stagehand-mask-root", rootToken);
+			}
+		} catch {
+			rootToken = null;
+		}
+		return {
+			...localRect,
+			rootToken,
+			position: style.position === "fixed" ? "fixed" : "absolute"
+		};
+	}
+	return {
+		x: rect.left + window.scrollX,
+		y: rect.top + window.scrollY,
+		width: rect.width,
+		height: rect.height,
+		rootToken: null
+	};
+}
+//#endregion
+//#region understudy/screenshotUtils.ts
+var screenshotQueues = /* @__PURE__ */ new WeakMap();
+/** Serialize page mutations, or the browser-wide activation/capture critical section. */
+async function withScreenshotLock(owner, capture, progress) {
+	progress.throwIfStopped();
+	const queue = screenshotQueues.get(owner) ?? {
+		tail: Promise.resolve(),
+		blocked: new AbortController()
+	};
+	queue.blocked.signal.throwIfAborted();
+	let started = false;
+	const onAbort = () => {
+		if (started) {
+			const error = progress.signal.reason;
+			queue.blocked.abort(new Error(`A previous capture is still recovering: ${error.message}`, { cause: error }));
+		}
+	};
+	progress.signal.addEventListener("abort", onAbort, { once: true });
+	const previous = queue.tail;
+	const pending = waitForScreenshot(previous, AbortSignal.any([queue.blocked.signal, progress.signal])).then(async () => {
+		queue.blocked.signal.throwIfAborted();
+		progress.throwIfStopped();
+		started = true;
+		try {
+			return await capture();
+		} finally {
+			started = false;
+		}
+	});
+	const settled = pending.then(() => {}, () => {});
+	const released = Promise.all([previous, settled]).then(() => {});
+	queue.tail = released;
+	screenshotQueues.set(owner, queue);
+	try {
+		return await pending;
+	} finally {
+		progress.signal.removeEventListener("abort", onAbort);
+		released.then(() => {
+			if (queue.tail === released) screenshotQueues.delete(owner);
+		});
+	}
+}
+/** Bound a wait by an operation or queue recovery signal. */
+async function waitForScreenshot(pending, signal) {
+	if (!signal) return await pending;
+	return await new Promise((resolve, reject) => {
+		const onAbort = () => {
+			signal.removeEventListener("abort", onAbort);
+			reject(signal.reason);
+		};
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+		pending.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+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 RangeError(`screenshot: clip.${key} must be a finite number`);
+	if (width <= 0 || height <= 0) throw new RangeError("screenshot: clip width/height must be positive");
+	return {
+		x,
+		y,
+		width,
+		height
+	};
+}
+async function computeScreenshotScale(page, mode, progress) {
+	if (mode !== "css") return void 0;
+	const dpr = await page.mainFrame().evaluate(() => {
+		const ratio = Number(window.devicePixelRatio || 1);
+		return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+	}, void 0, progress).catch(() => {
+		progress.throwIfStopped();
+		return 1;
+	});
+	progress.throwIfStopped();
+	return Math.min(2, Math.max(.1, 1 / (Number.isFinite(dpr) && dpr > 0 ? dpr : 1)));
+}
+async function setTransparentBackground(session, progress, cleanups) {
+	progress.throwIfStopped();
+	cleanups.push(async () => {
+		await session.send("Emulation.setDefaultBackgroundColorOverride", {}).catch(() => {});
+	});
+	await session.send("Emulation.setDefaultBackgroundColorOverride", { color: {
+		r: 0,
+		g: 0,
+		b: 0,
+		a: 0
+	} }).catch(() => {});
+	progress.throwIfStopped();
+}
+async function applyStyleToFrames(frames, css, label, progress, cleanups) {
+	const trimmed = css.trim();
+	if (!trimmed) return;
+	const token = `__v3_style_${label}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+	cleanups.push(async () => {
+		await Promise.all(frames.map((frame) => frame.evaluate((token) => {
+			try {
+				const doc = document;
+				if (!doc) return;
+				doc.querySelectorAll(`[data-stagehand-style="${token}"]`).forEach((node) => node.remove());
+			} catch {}
+		}, token).catch(() => {})));
+	});
+	await Promise.all(frames.map((frame) => frame.evaluate(({ css, token }) => {
+		try {
+			const doc = document;
+			if (!doc) return;
+			const style = doc.createElement("style");
+			style.setAttribute("data-stagehand-style", token);
+			style.textContent = css;
+			(doc.head || doc.documentElement || doc.body)?.appendChild(style);
+		} catch {}
+	}, {
+		css: trimmed,
+		token
+	}, progress).catch(() => {})));
+	progress.throwIfStopped();
+}
+async function disableAnimations(frames, progress, cleanups) {
+	await applyStyleToFrames(frames, `
+*,
+*::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;
+}`, "animations", progress, cleanups);
+	await Promise.all(frames.map((frame) => frame.evaluate(() => {
+		try {
+			const animations = typeof document.getAnimations === "function" ? document.getAnimations() : [];
+			for (const animation of animations) try {
+				const details = animation.effect?.getComputedTiming?.();
+				if (details && details.iterations !== Infinity) animation.finish?.();
+				else animation.cancel?.();
+			} catch {
+				animation.cancel?.();
+			}
+		} catch {}
+	}, void 0, progress).catch(() => {})));
+	progress.throwIfStopped();
+}
+async function hideCaret(frames, progress, cleanups) {
+	return applyStyleToFrames(frames, `
+input,
+textarea,
+[contenteditable],
+[contenteditable=""],
+[contenteditable="true"],
+[contenteditable="plaintext-only"],
+*:focus {
+  caret-color: transparent !important;
+}`, "caret", progress, cleanups);
+}
+async function applyMaskOverlays(locators, color, progress, cleanups) {
+	const rectsByFrame = /* @__PURE__ */ new Map();
+	const token = `__v3_mask_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+	cleanups.push(async () => {
+		await Promise.all(Array.from(rectsByFrame.keys()).map((frame) => frame.evaluate((token) => {
+			try {
+				const doc = document;
+				if (!doc) return;
+				doc.querySelectorAll(`[data-stagehand-mask="${token}"]`).forEach((node) => node.remove());
+				const roots = doc.querySelectorAll(`[data-stagehand-mask-root^="${token}"]`);
+				for (const root of roots) {
+					const prev = root.getAttribute("data-stagehand-mask-root-pos");
+					if (prev !== null) {
+						root.style.position = prev;
+						root.removeAttribute("data-stagehand-mask-root-pos");
+					}
+					root.removeAttribute("data-stagehand-mask-root");
+				}
+			} catch {}
+		}, token).catch(() => {})));
+	});
+	for (const locator of locators) try {
+		progress.throwIfStopped();
+		const resolved = "real" in locator ? await locator.real(progress) : locator;
+		const frame = resolved.getFrame();
+		const rects = rectsByFrame.get(frame) ?? [];
+		rectsByFrame.set(frame, rects);
+		rects.push(...await resolveMaskRects(resolved, token, progress));
+	} catch {
+		progress.throwIfStopped();
+	}
+	if ([...rectsByFrame.values()].every((rects) => rects.length === 0)) return;
+	await Promise.all(Array.from(rectsByFrame.entries()).map(([frame, rects]) => frame.evaluate(({ rects, color, token }) => {
+		try {
+			const doc = document;
+			if (!doc) return;
+			for (const rect of rects) {
+				const defaultRoot = doc.documentElement || doc.body;
+				if (!defaultRoot) return;
+				const root = rect.rootToken ? doc.querySelector(`[data-stagehand-mask-root="${rect.rootToken}"]`) || defaultRoot : defaultRoot;
+				if (!root) continue;
+				if (rect.rootToken) try {
+					const style = window.getComputedStyle(root);
+					if (style && style.position === "static") {
+						const rootEl = root;
+						if (!rootEl.hasAttribute("data-stagehand-mask-root-pos")) rootEl.setAttribute("data-stagehand-mask-root-pos", rootEl.style.position || "");
+						rootEl.style.position = "relative";
+					}
+				} catch {}
+				const el = doc.createElement("div");
+				el.setAttribute("data-stagehand-mask", token);
+				el.style.position = rect.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 = color;
+				el.style.pointerEvents = "none";
+				el.style.zIndex = "2147483647";
+				el.style.opacity = "1";
+				el.style.mixBlendMode = "normal";
+				root.appendChild(el);
+			}
+		} catch {}
+	}, {
+		rects,
+		color,
+		token
+	}, progress).catch(() => {})));
+	await progress.delay(100);
+}
+async function resolveMaskRects(locator, maskToken, progress) {
+	const session = locator.getFrame().session;
+	const resolved = await locator.resolveNodesForMask(progress);
+	const rects = [];
+	try {
+		for (const { objectId } of resolved) {
+			progress.throwIfStopped();
+			try {
+				const rect = await resolveMaskRectForObject(session, objectId, maskToken);
+				if (rect) rects.push(rect);
+			} catch {
+				progress.throwIfStopped();
+			}
+		}
+		return rects;
+	} finally {
+		await Promise.all(resolved.map(({ objectId }) => session.send("Runtime.releaseObject", { objectId }).catch(() => {})));
+	}
+}
+async function resolveMaskRectForObject(session, objectId, maskToken) {
+	const result = await session.send("Runtime.callFunctionOn", {
+		objectId,
+		functionDeclaration: resolveMaskRect.toString(),
+		arguments: [{ value: maskToken }],
+		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 {
+		x,
+		y,
+		width,
+		height,
+		rootToken: rect.rootToken && typeof rect.rootToken === "string" ? rect.rootToken : void 0,
+		position: rect.position === "fixed" ? "fixed" : "absolute"
+	};
+}
+async function runScreenshotCleanups(cleanups) {
+	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") await result;
+		} catch {}
+	}
+}
+//#endregion
 //#region understudy/page.ts
 /**
 * Page
@@ -57101,7 +57112,7 @@ var Page = class Page {
 	* timeout error is thrown.
 	* @param options.type Image format (`"png"` by default).
 	*/
-	async screenshot(options) {
+	async screenshot(options, parentProgress) {
 		const opts = options ?? {};
 		const type = opts.type ?? "png";
 		if (type !== "png" && type !== "jpeg") throw new TypeError("screenshot: unsupported image type");
@@ -57114,47 +57125,46 @@ var Page = class Page {
 		const clip = opts.clip ? normalizeScreenshotClip(opts.clip) : void 0;
 		const maskLocators = opts.mask ?? [];
 		const cleanupTasks = [];
-		const exec = async (signal) => {
+		let failure;
+		const exec = async (progress) => {
 			try {
-				const captureScale = await waitForScreenshot(computeScreenshotScale(this, scaleMode), signal);
-				if (opts.omitBackground) {
-					signal.throwIfAborted();
-					cleanupTasks.push(await setTransparentBackground(this.mainSession));
-				}
-				if (animationsMode === "disabled") {
-					signal.throwIfAborted();
-					cleanupTasks.push(await disableAnimations(frames));
-				}
-				if (caretMode === "hide") {
-					signal.throwIfAborted();
-					cleanupTasks.push(await hideCaret(frames));
-				}
-				if (opts.style && opts.style.trim()) {
-					signal.throwIfAborted();
-					cleanupTasks.push(await applyStyleToFrames(frames, opts.style, "custom"));
-				}
-				if (maskLocators.length > 0) {
-					signal.throwIfAborted();
-					cleanupTasks.push(await applyMaskOverlays(maskLocators, opts.maskColor ?? "#FF00FF"));
-				}
-				return await waitForScreenshot(withScreenshotLock(this.conn, () => this.mainFrameWrapper.screenshot({
+				const captureScale = await computeScreenshotScale(this, scaleMode, progress);
+				if (opts.omitBackground) await setTransparentBackground(this.mainSession, progress, cleanupTasks);
+				if (animationsMode === "disabled") await disableAnimations(frames, progress, cleanupTasks);
+				if (caretMode === "hide") await hideCaret(frames, progress, cleanupTasks);
+				if (opts.style && opts.style.trim()) await applyStyleToFrames(frames, opts.style, "custom", progress, cleanupTasks);
+				if (maskLocators.length > 0) await applyMaskOverlays(maskLocators, opts.maskColor ?? "#FF00FF", progress, cleanupTasks);
+				return await withScreenshotLock(this.conn, () => this.mainFrameWrapper.screenshot({
 					fullPage: opts.fullPage,
 					clip,
 					type,
 					quality: type === "jpeg" ? opts.quality : void 0,
-					scale: captureScale,
-					signal
-				}), void 0), signal);
+					scale: captureScale
+				}, progress), progress);
+			} catch (error) {
+				progress.throwIfStopped();
+				failure = { error };
+				throw error;
 			} finally {
 				await runScreenshotCleanups(cleanupTasks);
 			}
 		};
-		return await withScreenshotLock(this, exec, opts.timeout);
+		try {
+			return await runWithProgress(parentProgress ?? {
+				name: "screenshot",
+				timeout: opts.timeout ?? 0
+			}, (progress) => withScreenshotLock(this, () => exec(progress), progress));
+		} catch (error) {
+			throw failure ? failure.error : error;
+		}
 	}
 	/** Keep the PDF base64-encoded for transport; SDKs decode it to bytes. */
-	async pdf(options) {
+	async pdf(options, parentProgress) {
 		const { timeout = 3e4, width, height, margin, tagged = false, outline = false, ...printOptions } = options ?? {};
-		return await withScreenshotLock(this, async () => {
+		return await runWithProgress(parentProgress ?? {
+			name: "pdf",
+			timeout
+		}, (progress) => withScreenshotLock(this, async () => {
 			const { data } = await this.mainSession.send("Page.printToPDF", {
 				...printOptions,
 				paperWidth: width,
@@ -57168,7 +57178,7 @@ var Page = class Page {
 				transferMode: "ReturnAsBase64"
 			});
 			return { data };
-		}, timeout, "pdf");
+		}, progress));
 	}
 	/**
 	* specifies additional HTTP headers to be included in every request sent by

{stagehand-4.2.0a0.dev1556 → stagehand-4.2.0a0.dev1558}/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-1562d3506204452eb76a4653fc4fabc4c7cc1e3e'
+STAGEHAND_PROTOCOL_VERSION = '2.1.0-alpha-173fe1ff6dae5dcadf512a16a41770e16f453330'