@browserbasehq/stagehand 4.1.0 → 4.1.1-alpha-e9cb6aaf166da8342018ec8d3f9e5290955ea953

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -12627,6 +12627,12 @@ function createCallbackBatchController(router) {
12627
12627
  const stagehand = {
12628
12628
  page,
12629
12629
  context: createCallbackContextFacade(context),
12630
+ evaluateWithShadowRoots: async (pageId, functionSource) => {
12631
+ if (controller.signal.aborted) throw controller.signal.reason;
12632
+ const result = await router.runtime.evaluateWithShadowRoots(pageId, functionSource);
12633
+ if (controller.signal.aborted) throw controller.signal.reason;
12634
+ return result;
12635
+ },
12630
12636
  act: async (instruction, operationOptions) => {
12631
12637
  const { page: operationPage, ...clientOptions } = StagehandClientActOptionsSchema.parse(operationOptions ?? {});
12632
12638
  const targetPage = await resolveOperationPage(operationPage);
@@ -13007,6 +13013,18 @@ var DuplicatePageEventSubscriptionError = class extends Error {
13007
13013
  this.name = "DuplicatePageEventSubscriptionError";
13008
13014
  }
13009
13015
  };
13016
+ var ShadowRootEvaluationError = class extends Error {
13017
+ constructor() {
13018
+ super("Shadow-root evaluation failed");
13019
+ this.name = "ShadowRootEvaluationError";
13020
+ }
13021
+ };
13022
+ var ShadowRootEvaluationUnavailableError = class extends Error {
13023
+ constructor() {
13024
+ super("Shadow-root evaluation is unavailable");
13025
+ this.name = "ShadowRootEvaluationUnavailableError";
13026
+ }
13027
+ };
13010
13028
  //#endregion
13011
13029
  //#region dom/locatorScripts/scripts.ts
13012
13030
  function ensureFileInputElement() {
@@ -16123,6 +16141,418 @@ async function act$1(params) {
16123
16141
  };
16124
16142
  }
16125
16143
  //#endregion
16144
+ //#region dom/screenshotScripts/resolveMaskRect.ts
16145
+ function resolveMaskRect(maskToken) {
16146
+ function safeClosest(el, selector) {
16147
+ try {
16148
+ return el && typeof el.closest === "function" ? el.closest(selector) : null;
16149
+ } catch {
16150
+ return null;
16151
+ }
16152
+ }
16153
+ function safeMatches(el, selector) {
16154
+ try {
16155
+ return !!el && typeof el.matches === "function" && el.matches(selector);
16156
+ } catch {
16157
+ return false;
16158
+ }
16159
+ }
16160
+ function findTopLayerRoot(el) {
16161
+ const dialog = safeClosest(el, "dialog[open]");
16162
+ if (dialog) return dialog;
16163
+ const popover = safeClosest(el, "[popover]");
16164
+ if (popover && safeMatches(popover, ":popover-open")) return popover;
16165
+ return null;
16166
+ }
16167
+ if (!this || typeof this.getBoundingClientRect !== "function") return null;
16168
+ const rect = this.getBoundingClientRect();
16169
+ if (!rect) return null;
16170
+ const style = window.getComputedStyle(this);
16171
+ if (!style) return null;
16172
+ if (style.visibility === "hidden" || style.display === "none") return null;
16173
+ if (rect.width <= 0 || rect.height <= 0) return null;
16174
+ const root = findTopLayerRoot(this);
16175
+ if (root) {
16176
+ const rootRect = root.getBoundingClientRect();
16177
+ const rootClientLeft = root.clientLeft || 0;
16178
+ const rootClientTop = root.clientTop || 0;
16179
+ const rootScrollLeft = root.scrollLeft || 0;
16180
+ const rootScrollTop = root.scrollTop || 0;
16181
+ let localRect = {
16182
+ x: rect.left - rootRect.left - rootClientLeft + rootScrollLeft,
16183
+ y: rect.top - rootRect.top - rootClientTop + rootScrollTop,
16184
+ width: rect.width,
16185
+ height: rect.height
16186
+ };
16187
+ try {
16188
+ const rootElement = root;
16189
+ const transformProperties = [
16190
+ "transform",
16191
+ "translate",
16192
+ "rotate",
16193
+ "scale"
16194
+ ];
16195
+ const previous = transformProperties.map((property) => ({
16196
+ property,
16197
+ value: rootElement.style.getPropertyValue(property),
16198
+ priority: rootElement.style.getPropertyPriority(property)
16199
+ }));
16200
+ const previousTransition = {
16201
+ value: rootElement.style.getPropertyValue("transition"),
16202
+ priority: rootElement.style.getPropertyPriority("transition")
16203
+ };
16204
+ const previousWillChange = {
16205
+ value: rootElement.style.getPropertyValue("will-change"),
16206
+ priority: rootElement.style.getPropertyPriority("will-change")
16207
+ };
16208
+ try {
16209
+ rootElement.style.setProperty("transition", "none", "important");
16210
+ rootElement.style.setProperty("will-change", "transform", "important");
16211
+ root.getBoundingClientRect();
16212
+ for (const property of transformProperties) rootElement.style.setProperty(property, "none", "important");
16213
+ const untransformedRootRect = root.getBoundingClientRect();
16214
+ const untransformedTargetRect = this.getBoundingClientRect();
16215
+ if (untransformedTargetRect.width > 0 && untransformedTargetRect.height > 0 && Number.isFinite(untransformedRootRect.left) && Number.isFinite(untransformedRootRect.top)) {
16216
+ const maskBleed = 3;
16217
+ localRect = {
16218
+ x: untransformedTargetRect.left - untransformedRootRect.left - rootClientLeft + rootScrollLeft - maskBleed,
16219
+ y: untransformedTargetRect.top - untransformedRootRect.top - rootClientTop + rootScrollTop - maskBleed,
16220
+ width: untransformedTargetRect.width + maskBleed * 2,
16221
+ height: untransformedTargetRect.height + maskBleed * 2
16222
+ };
16223
+ }
16224
+ } finally {
16225
+ for (const { property, value, priority } of previous) if (value) rootElement.style.setProperty(property, value, priority);
16226
+ else rootElement.style.removeProperty(property);
16227
+ if (previousWillChange.value) rootElement.style.setProperty("will-change", previousWillChange.value, previousWillChange.priority);
16228
+ else rootElement.style.removeProperty("will-change");
16229
+ root.getBoundingClientRect();
16230
+ if (previousTransition.value) rootElement.style.setProperty("transition", previousTransition.value, previousTransition.priority);
16231
+ else rootElement.style.removeProperty("transition");
16232
+ }
16233
+ } catch {}
16234
+ let rootToken = null;
16235
+ if (maskToken) try {
16236
+ const existing = root.getAttribute("data-stagehand-mask-root");
16237
+ if (existing && existing.startsWith(maskToken)) rootToken = existing;
16238
+ else {
16239
+ rootToken = maskToken + "_root_" + Math.random().toString(36).slice(2);
16240
+ root.setAttribute("data-stagehand-mask-root", rootToken);
16241
+ }
16242
+ } catch {
16243
+ rootToken = null;
16244
+ }
16245
+ return {
16246
+ ...localRect,
16247
+ rootToken,
16248
+ position: style.position === "fixed" ? "fixed" : "absolute"
16249
+ };
16250
+ }
16251
+ return {
16252
+ x: rect.left + window.scrollX,
16253
+ y: rect.top + window.scrollY,
16254
+ width: rect.width,
16255
+ height: rect.height,
16256
+ rootToken: null
16257
+ };
16258
+ }
16259
+ //#endregion
16260
+ //#region understudy/screenshotUtils.ts
16261
+ var screenshotQueues = /* @__PURE__ */ new WeakMap();
16262
+ /** Serialize page mutations, or the browser-wide activation/capture critical section. */
16263
+ async function withScreenshotLock(owner, capture, timeout) {
16264
+ const queue = screenshotQueues.get(owner) ?? {
16265
+ tail: Promise.resolve(),
16266
+ blocked: new AbortController()
16267
+ };
16268
+ queue.blocked.signal.throwIfAborted();
16269
+ const controller = new AbortController();
16270
+ let started = false;
16271
+ const timer = typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0 ? setTimeout(() => {
16272
+ controller.abort(new TimeoutError("screenshot", timeout));
16273
+ if (started) queue.blocked.abort(/* @__PURE__ */ new Error("screenshot: a previous timed-out capture is still recovering"));
16274
+ }, Math.min(timeout, 2147483647)) : void 0;
16275
+ const pending = queue.tail.then(() => {
16276
+ queue.blocked.signal.throwIfAborted();
16277
+ controller.signal.throwIfAborted();
16278
+ started = true;
16279
+ return capture(controller.signal);
16280
+ });
16281
+ const released = pending.then(() => {}, () => {});
16282
+ queue.tail = released;
16283
+ screenshotQueues.set(owner, queue);
16284
+ try {
16285
+ return await waitForScreenshot(waitForScreenshot(pending, queue.blocked.signal), controller.signal);
16286
+ } finally {
16287
+ if (timer !== void 0) clearTimeout(timer);
16288
+ released.then(() => {
16289
+ if (queue.tail === released) screenshotQueues.delete(owner);
16290
+ });
16291
+ }
16292
+ }
16293
+ /** Stop waiting for a stalled CDP capture; its eventual response cannot resume cleanup. */
16294
+ async function waitForScreenshot(pending, signal) {
16295
+ if (!signal) return await pending;
16296
+ return await new Promise((resolve, reject) => {
16297
+ const onAbort = () => {
16298
+ signal.removeEventListener("abort", onAbort);
16299
+ reject(signal.reason);
16300
+ };
16301
+ if (signal.aborted) onAbort();
16302
+ else signal.addEventListener("abort", onAbort, { once: true });
16303
+ pending.then((value) => {
16304
+ signal.removeEventListener("abort", onAbort);
16305
+ resolve(value);
16306
+ }, (error) => {
16307
+ signal.removeEventListener("abort", onAbort);
16308
+ reject(error);
16309
+ });
16310
+ });
16311
+ }
16312
+ function collectFramesForScreenshot(page) {
16313
+ const seen = /* @__PURE__ */ new Map();
16314
+ const main = page.mainFrame();
16315
+ seen.set(main.frameId, main);
16316
+ for (const frame of page.frames()) seen.set(frame.frameId, frame);
16317
+ return Array.from(seen.values());
16318
+ }
16319
+ function normalizeScreenshotClip(clip) {
16320
+ const x = Number(clip.x);
16321
+ const y = Number(clip.y);
16322
+ const width = Number(clip.width);
16323
+ const height = Number(clip.height);
16324
+ for (const [key, value] of Object.entries({
16325
+ x,
16326
+ y,
16327
+ width,
16328
+ height
16329
+ })) if (!Number.isFinite(value)) throw new RangeError(`screenshot: clip.${key} must be a finite number`);
16330
+ if (width <= 0 || height <= 0) throw new RangeError("screenshot: clip width/height must be positive");
16331
+ return {
16332
+ x,
16333
+ y,
16334
+ width,
16335
+ height
16336
+ };
16337
+ }
16338
+ async function computeScreenshotScale(page, mode) {
16339
+ if (mode !== "css") return void 0;
16340
+ try {
16341
+ const dpr = await page.mainFrame().evaluate(() => {
16342
+ const ratio = Number(window.devicePixelRatio || 1);
16343
+ return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
16344
+ }).catch(() => 1);
16345
+ return Math.min(2, Math.max(.1, 1 / (Number.isFinite(dpr) && dpr > 0 ? dpr : 1)));
16346
+ } catch {
16347
+ return 1;
16348
+ }
16349
+ }
16350
+ async function setTransparentBackground(session) {
16351
+ await session.send("Emulation.setDefaultBackgroundColorOverride", { color: {
16352
+ r: 0,
16353
+ g: 0,
16354
+ b: 0,
16355
+ a: 0
16356
+ } }).catch(() => {});
16357
+ return async () => {
16358
+ await session.send("Emulation.setDefaultBackgroundColorOverride", {}).catch(() => {});
16359
+ };
16360
+ }
16361
+ async function applyStyleToFrames(frames, css, label) {
16362
+ const trimmed = css.trim();
16363
+ if (!trimmed) return async () => {};
16364
+ const token = `__v3_style_${label}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
16365
+ await Promise.all(frames.map((frame) => frame.evaluate(({ css, token }) => {
16366
+ try {
16367
+ const doc = document;
16368
+ if (!doc) return;
16369
+ const style = doc.createElement("style");
16370
+ style.setAttribute("data-stagehand-style", token);
16371
+ style.textContent = css;
16372
+ (doc.head || doc.documentElement || doc.body)?.appendChild(style);
16373
+ } catch {}
16374
+ }, {
16375
+ css: trimmed,
16376
+ token
16377
+ }).catch(() => {})));
16378
+ return async () => {
16379
+ await Promise.all(frames.map((frame) => frame.evaluate((token) => {
16380
+ try {
16381
+ const doc = document;
16382
+ if (!doc) return;
16383
+ doc.querySelectorAll(`[data-stagehand-style="${token}"]`).forEach((node) => node.remove());
16384
+ } catch {}
16385
+ }, token).catch(() => {})));
16386
+ };
16387
+ }
16388
+ async function disableAnimations(frames) {
16389
+ const cleanup = await applyStyleToFrames(frames, `
16390
+ *,
16391
+ *::before,
16392
+ *::after {
16393
+ animation-delay: 0s !important;
16394
+ animation-duration: 0s !important;
16395
+ animation-iteration-count: 1 !important;
16396
+ animation-play-state: paused !important;
16397
+ transition-property: none !important;
16398
+ transition-duration: 0s !important;
16399
+ transition-delay: 0s !important;
16400
+ }`, "animations");
16401
+ await Promise.all(frames.map((frame) => frame.evaluate(() => {
16402
+ try {
16403
+ const animations = typeof document.getAnimations === "function" ? document.getAnimations() : [];
16404
+ for (const animation of animations) try {
16405
+ const details = animation.effect?.getComputedTiming?.();
16406
+ if (details && details.iterations !== Infinity) animation.finish?.();
16407
+ else animation.cancel?.();
16408
+ } catch {
16409
+ animation.cancel?.();
16410
+ }
16411
+ } catch {}
16412
+ }).catch(() => {})));
16413
+ return cleanup;
16414
+ }
16415
+ async function hideCaret(frames) {
16416
+ return applyStyleToFrames(frames, `
16417
+ input,
16418
+ textarea,
16419
+ [contenteditable],
16420
+ [contenteditable=""],
16421
+ [contenteditable="true"],
16422
+ [contenteditable="plaintext-only"],
16423
+ *:focus {
16424
+ caret-color: transparent !important;
16425
+ }`, "caret");
16426
+ }
16427
+ async function applyMaskOverlays(locators, color) {
16428
+ const rectsByFrame = /* @__PURE__ */ new Map();
16429
+ const token = `__v3_mask_${Date.now()}_${Math.random().toString(36).slice(2)}`;
16430
+ for (const locator of locators) try {
16431
+ const info = await resolveMaskRects("real" in locator ? await locator.real() : locator, token);
16432
+ if (!info) continue;
16433
+ const entry = rectsByFrame.get(info.frame) ?? {
16434
+ rects: [],
16435
+ rootTokens: /* @__PURE__ */ new Set()
16436
+ };
16437
+ entry.rects.push(...info.rects);
16438
+ for (const rect of info.rects) if (rect.rootToken) entry.rootTokens.add(rect.rootToken);
16439
+ rectsByFrame.set(info.frame, entry);
16440
+ } catch {}
16441
+ if (rectsByFrame.size === 0) return async () => {};
16442
+ await Promise.all(Array.from(rectsByFrame.entries()).map(([frame, { rects }]) => frame.evaluate(({ rects, color, token }) => {
16443
+ try {
16444
+ const doc = document;
16445
+ if (!doc) return;
16446
+ for (const rect of rects) {
16447
+ const defaultRoot = doc.documentElement || doc.body;
16448
+ if (!defaultRoot) return;
16449
+ const root = rect.rootToken ? doc.querySelector(`[data-stagehand-mask-root="${rect.rootToken}"]`) || defaultRoot : defaultRoot;
16450
+ if (!root) continue;
16451
+ if (rect.rootToken) try {
16452
+ const style = window.getComputedStyle(root);
16453
+ if (style && style.position === "static") {
16454
+ const rootEl = root;
16455
+ if (!rootEl.hasAttribute("data-stagehand-mask-root-pos")) rootEl.setAttribute("data-stagehand-mask-root-pos", rootEl.style.position || "");
16456
+ rootEl.style.position = "relative";
16457
+ }
16458
+ } catch {}
16459
+ const el = doc.createElement("div");
16460
+ el.setAttribute("data-stagehand-mask", token);
16461
+ el.style.position = rect.position ?? "absolute";
16462
+ el.style.left = `${rect.x}px`;
16463
+ el.style.top = `${rect.y}px`;
16464
+ el.style.width = `${rect.width}px`;
16465
+ el.style.height = `${rect.height}px`;
16466
+ el.style.backgroundColor = color;
16467
+ el.style.pointerEvents = "none";
16468
+ el.style.zIndex = "2147483647";
16469
+ el.style.opacity = "1";
16470
+ el.style.mixBlendMode = "normal";
16471
+ root.appendChild(el);
16472
+ }
16473
+ } catch {}
16474
+ }, {
16475
+ rects,
16476
+ color,
16477
+ token
16478
+ }).catch(() => {})));
16479
+ await new Promise((resolve) => setTimeout(resolve, 100));
16480
+ return async () => {
16481
+ await Promise.all(Array.from(rectsByFrame.entries()).map(([frame, { rootTokens }]) => frame.evaluate(({ token, rootTokens }) => {
16482
+ try {
16483
+ const doc = document;
16484
+ if (!doc) return;
16485
+ doc.querySelectorAll(`[data-stagehand-mask="${token}"]`).forEach((node) => node.remove());
16486
+ for (const rootToken of rootTokens) {
16487
+ const root = doc.querySelector(`[data-stagehand-mask-root="${rootToken}"]`);
16488
+ if (!root) continue;
16489
+ const prev = root.getAttribute("data-stagehand-mask-root-pos");
16490
+ if (prev !== null) {
16491
+ root.style.position = prev;
16492
+ root.removeAttribute("data-stagehand-mask-root-pos");
16493
+ }
16494
+ root.removeAttribute("data-stagehand-mask-root");
16495
+ }
16496
+ } catch {}
16497
+ }, {
16498
+ token,
16499
+ rootTokens: Array.from(rootTokens)
16500
+ }).catch(() => {})));
16501
+ };
16502
+ }
16503
+ async function resolveMaskRects(locator, maskToken) {
16504
+ const frame = locator.getFrame();
16505
+ const session = frame.session;
16506
+ try {
16507
+ const resolved = await locator.resolveNodesForMask();
16508
+ const rects = [];
16509
+ for (const { objectId } of resolved) try {
16510
+ const rect = await resolveMaskRectForObject(session, objectId, maskToken);
16511
+ if (rect) rects.push(rect);
16512
+ } catch {} finally {
16513
+ await session.send("Runtime.releaseObject", { objectId }).catch(() => {});
16514
+ }
16515
+ if (!rects.length) return null;
16516
+ return {
16517
+ frame,
16518
+ rects
16519
+ };
16520
+ } catch {
16521
+ return null;
16522
+ }
16523
+ }
16524
+ async function resolveMaskRectForObject(session, objectId, maskToken) {
16525
+ const result = await session.send("Runtime.callFunctionOn", {
16526
+ objectId,
16527
+ functionDeclaration: resolveMaskRect.toString(),
16528
+ arguments: [{ value: maskToken }],
16529
+ returnByValue: true
16530
+ });
16531
+ if (result.exceptionDetails) return null;
16532
+ const rect = result.result.value;
16533
+ if (!rect) return null;
16534
+ const { x, y, width, height } = rect;
16535
+ if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
16536
+ return {
16537
+ x,
16538
+ y,
16539
+ width,
16540
+ height,
16541
+ rootToken: rect.rootToken && typeof rect.rootToken === "string" ? rect.rootToken : void 0,
16542
+ position: rect.position === "fixed" ? "fixed" : "absolute"
16543
+ };
16544
+ }
16545
+ async function runScreenshotCleanups(cleanups) {
16546
+ for (let i = cleanups.length - 1; i >= 0; i -= 1) {
16547
+ const fn = cleanups[i];
16548
+ if (!fn) continue;
16549
+ try {
16550
+ const result = fn();
16551
+ if (result && typeof result.then === "function") await result;
16552
+ } catch {}
16553
+ }
16554
+ }
16555
+ //#endregion
16126
16556
  //#region understudy/frame.ts
16127
16557
  function base64ToBytes$1(base64) {
16128
16558
  const binary = globalThis.atob(base64);
@@ -16268,7 +16698,9 @@ var Frame = class Frame {
16268
16698
  }
16269
16699
  /** Page.captureScreenshot (frame-scoped session) */
16270
16700
  async screenshot(options) {
16271
- await this.session.send("Page.enable");
16701
+ const signal = options?.signal;
16702
+ signal?.throwIfAborted();
16703
+ await waitForScreenshot(this.session.send("Page.enable"), signal);
16272
16704
  const format = options?.type ?? "png";
16273
16705
  const params = {
16274
16706
  format,
@@ -16289,7 +16721,8 @@ var Frame = class Frame {
16289
16721
  const q = Math.round(options.quality);
16290
16722
  params.quality = Math.min(100, Math.max(0, q));
16291
16723
  }
16292
- const { data } = await this.session.send("Page.captureScreenshot", params);
16724
+ await waitForScreenshot(this.session.send("Page.bringToFront"), signal);
16725
+ const { data } = await waitForScreenshot(this.session.send("Page.captureScreenshot", params), signal);
16293
16726
  return base64ToBytes$1(data);
16294
16727
  }
16295
16728
  /** Child frames via Page.getFrameTree */
@@ -16838,7 +17271,7 @@ async function domMapsForSession(session, frameId, pierce, encode, attemptOwnerL
16838
17271
  */
16839
17272
  async function buildSessionDomIndex(session, pierce) {
16840
17273
  await session.send("DOM.enable").catch(() => {});
16841
- const root = await getDomTreeWithFallback(session, pierce);
17274
+ const root = await getDomTreeWithFallback(session, true);
16842
17275
  const absByBe = /* @__PURE__ */ new Map();
16843
17276
  const tagByBe = /* @__PURE__ */ new Map();
16844
17277
  const scrollByBe = /* @__PURE__ */ new Map();
@@ -16887,7 +17320,7 @@ async function buildSessionDomIndex(session, pierce) {
16887
17320
  });
16888
17321
  }
16889
17322
  }
16890
- for (const sr of node.shadowRoots ?? []) stack.push({
17323
+ for (const sr of pierce ? node.shadowRoots ?? [] : []) stack.push({
16891
17324
  node: sr,
16892
17325
  xp: joinXPath(xp, "//"),
16893
17326
  docRootBe,
@@ -17161,10 +17594,12 @@ async function collectPerFrameMaps(page, context, sessionToIndex, options, pierc
17161
17594
  const parentId = context.parentByFrame.get(frameId);
17162
17595
  const sameSessionAsParent = !!parentId && ownerSession(page, parentId) === sess;
17163
17596
  const docRootBe = await resolveFrameDocRootBackendId(page, frameId, idx, sameSessionAsParent);
17597
+ if (docRootBe === void 0) continue;
17164
17598
  const tagNameMap = {};
17165
17599
  const xpathMap = {};
17166
17600
  const scrollableMap = {};
17167
- const isIgnoredBackendNode = makeIsIgnoredBackendNode(frameId, idx, exclusionIntervalsByFrame);
17601
+ const isExcluded = makeIsIgnoredBackendNode(frameId, idx, exclusionIntervalsByFrame);
17602
+ const isIgnoredBackendNode = (backendId) => isExcluded?.(backendId) === true || !pierce && idx.docRootOf.get(backendId) !== docRootBe;
17168
17603
  const enc = (be) => `${page.getOrdinal(frameId)}-${be}`;
17169
17604
  const baseAbs = idx.absByBe.get(docRootBe) ?? "/";
17170
17605
  for (const [be, nodeAbs] of idx.absByBe.entries()) {
@@ -17230,9 +17665,11 @@ async function resolveIgnoredNodesForLocator(page, locator, context, sessionToIn
17230
17665
  const idx = ownerSessionIndexForFrame(page, targetFrameId, sessionToIndex);
17231
17666
  if (!idx) return [];
17232
17667
  const parentId = context.parentByFrame.get(targetFrameId);
17668
+ const backendNodeId = await resolveFrameDocRootBackendId(page, targetFrameId, idx, !!parentId && ownerSession(page, parentId) === ownerSession(page, targetFrameId));
17669
+ if (backendNodeId === void 0) return [];
17233
17670
  return [{
17234
17671
  frameId: targetFrameId,
17235
- backendNodeId: await resolveFrameDocRootBackendId(page, targetFrameId, idx, !!parentId && ownerSession(page, parentId) === ownerSession(page, targetFrameId))
17672
+ backendNodeId
17236
17673
  }];
17237
17674
  }
17238
17675
  return resolveIgnoredNodesInFrame(page, targetFrameId, {
@@ -17289,9 +17726,11 @@ async function buildFrameExclusionIntervals(page, context, sessionToIndex, ignor
17289
17726
  if (!idx) return;
17290
17727
  const parentId = context.parentByFrame.get(frameId);
17291
17728
  const docRootBe = await resolveFrameDocRootBackendId(page, frameId, idx, !!parentId && ownerSession(page, parentId) === ownerSession(page, frameId));
17292
- const start = idx.enterByBe.get(docRootBe);
17293
- const end = idx.exitByBe.get(docRootBe);
17294
- if (typeof start === "number" && typeof end === "number") pushInterval(frameId, start, end);
17729
+ if (docRootBe !== void 0) {
17730
+ const start = idx.enterByBe.get(docRootBe);
17731
+ const end = idx.exitByBe.get(docRootBe);
17732
+ if (typeof start === "number" && typeof end === "number") pushInterval(frameId, start, end);
17733
+ }
17295
17734
  for (const childFrameId of listChildrenOf(context.parentByFrame, frameId)) await excludeFrameSubtree(childFrameId);
17296
17735
  };
17297
17736
  const excludeIgnoredNode = async (frameId, backendNodeId) => {
@@ -17385,7 +17824,6 @@ async function resolveFrameDocRootBackendId(page, frameId, idx, sameSessionAsPar
17385
17824
  if (typeof docRootBe === "number") return docRootBe;
17386
17825
  }
17387
17826
  } catch {}
17388
- return idx.rootBackend;
17389
17827
  }
17390
17828
  /**
17391
17829
  * Step 4 – walk the frame tree (parent-first) to compute absolute prefixes for
@@ -53630,6 +54068,46 @@ function createOtlpSpanProcessor(traces) {
53630
54068
  });
53631
54069
  }
53632
54070
  //#endregion
54071
+ //#region understudy/shadowRootEvaluation.ts
54072
+ /** Evaluate in the main world with temporary references to author closed roots. */
54073
+ async function evaluateWithShadowRoots(session, evaluate, functionSource) {
54074
+ const { root } = await session.send("DOM.getDocument", {
54075
+ depth: -1,
54076
+ pierce: true
54077
+ });
54078
+ const closedIds = [];
54079
+ const visit = (node) => {
54080
+ if (node.shadowRootType === "closed") closedIds.push(node.backendNodeId);
54081
+ for (const child of node.children ?? []) visit(child);
54082
+ for (const shadow of node.shadowRoots ?? []) if (shadow.shadowRootType !== "user-agent") visit(shadow);
54083
+ };
54084
+ visit(root);
54085
+ if (!closedIds.length) return await evaluate(`(${functionSource})([])`);
54086
+ const objectGroup = `stagehand-shadow-query-${crypto.randomUUID()}`;
54087
+ try {
54088
+ const objects = [];
54089
+ for (const backendNodeId of closedIds) {
54090
+ const { object } = await session.send("DOM.resolveNode", {
54091
+ backendNodeId,
54092
+ objectGroup
54093
+ });
54094
+ if (!object.objectId) throw new ShadowRootEvaluationError();
54095
+ objects.push({ objectId: object.objectId });
54096
+ }
54097
+ const response = await session.send("Runtime.callFunctionOn", {
54098
+ objectId: objects[0].objectId,
54099
+ functionDeclaration: `function(...roots) { return (${functionSource})(roots); }`,
54100
+ arguments: objects,
54101
+ awaitPromise: true,
54102
+ returnByValue: true
54103
+ });
54104
+ if (response.exceptionDetails) throw new ShadowRootEvaluationError();
54105
+ return response.result.value;
54106
+ } finally {
54107
+ await session.send("Runtime.releaseObjectGroup", { objectGroup }).catch(() => {});
54108
+ }
54109
+ }
54110
+ //#endregion
53633
54111
  //#region understudy/frameRegistry.ts
53634
54112
  /** Minimal “shell” CDP frame used when we haven’t yet seen a real Frame from events. */
53635
54113
  function shellFrame(id) {
@@ -54845,383 +55323,6 @@ async function normalizeInitScriptSource(script, arg, caller = DEFAULT_CALLER) {
54845
55323
  throw new TypeError(`${caller}: provide a string, function, or an object with content.`);
54846
55324
  }
54847
55325
  //#endregion
54848
- //#region dom/screenshotScripts/resolveMaskRect.ts
54849
- function resolveMaskRect(maskToken) {
54850
- function safeClosest(el, selector) {
54851
- try {
54852
- return el && typeof el.closest === "function" ? el.closest(selector) : null;
54853
- } catch {
54854
- return null;
54855
- }
54856
- }
54857
- function safeMatches(el, selector) {
54858
- try {
54859
- return !!el && typeof el.matches === "function" && el.matches(selector);
54860
- } catch {
54861
- return false;
54862
- }
54863
- }
54864
- function findTopLayerRoot(el) {
54865
- const dialog = safeClosest(el, "dialog[open]");
54866
- if (dialog) return dialog;
54867
- const popover = safeClosest(el, "[popover]");
54868
- if (popover && safeMatches(popover, ":popover-open")) return popover;
54869
- return null;
54870
- }
54871
- if (!this || typeof this.getBoundingClientRect !== "function") return null;
54872
- const rect = this.getBoundingClientRect();
54873
- if (!rect) return null;
54874
- const style = window.getComputedStyle(this);
54875
- if (!style) return null;
54876
- if (style.visibility === "hidden" || style.display === "none") return null;
54877
- if (rect.width <= 0 || rect.height <= 0) return null;
54878
- const root = findTopLayerRoot(this);
54879
- if (root) {
54880
- const rootRect = root.getBoundingClientRect();
54881
- const rootClientLeft = root.clientLeft || 0;
54882
- const rootClientTop = root.clientTop || 0;
54883
- const rootScrollLeft = root.scrollLeft || 0;
54884
- const rootScrollTop = root.scrollTop || 0;
54885
- let localRect = {
54886
- x: rect.left - rootRect.left - rootClientLeft + rootScrollLeft,
54887
- y: rect.top - rootRect.top - rootClientTop + rootScrollTop,
54888
- width: rect.width,
54889
- height: rect.height
54890
- };
54891
- try {
54892
- const rootElement = root;
54893
- const transformProperties = [
54894
- "transform",
54895
- "translate",
54896
- "rotate",
54897
- "scale"
54898
- ];
54899
- const previous = transformProperties.map((property) => ({
54900
- property,
54901
- value: rootElement.style.getPropertyValue(property),
54902
- priority: rootElement.style.getPropertyPriority(property)
54903
- }));
54904
- const previousTransition = {
54905
- value: rootElement.style.getPropertyValue("transition"),
54906
- priority: rootElement.style.getPropertyPriority("transition")
54907
- };
54908
- const previousWillChange = {
54909
- value: rootElement.style.getPropertyValue("will-change"),
54910
- priority: rootElement.style.getPropertyPriority("will-change")
54911
- };
54912
- try {
54913
- rootElement.style.setProperty("transition", "none", "important");
54914
- rootElement.style.setProperty("will-change", "transform", "important");
54915
- root.getBoundingClientRect();
54916
- for (const property of transformProperties) rootElement.style.setProperty(property, "none", "important");
54917
- const untransformedRootRect = root.getBoundingClientRect();
54918
- const untransformedTargetRect = this.getBoundingClientRect();
54919
- if (untransformedTargetRect.width > 0 && untransformedTargetRect.height > 0 && Number.isFinite(untransformedRootRect.left) && Number.isFinite(untransformedRootRect.top)) {
54920
- const maskBleed = 3;
54921
- localRect = {
54922
- x: untransformedTargetRect.left - untransformedRootRect.left - rootClientLeft + rootScrollLeft - maskBleed,
54923
- y: untransformedTargetRect.top - untransformedRootRect.top - rootClientTop + rootScrollTop - maskBleed,
54924
- width: untransformedTargetRect.width + maskBleed * 2,
54925
- height: untransformedTargetRect.height + maskBleed * 2
54926
- };
54927
- }
54928
- } finally {
54929
- for (const { property, value, priority } of previous) if (value) rootElement.style.setProperty(property, value, priority);
54930
- else rootElement.style.removeProperty(property);
54931
- if (previousWillChange.value) rootElement.style.setProperty("will-change", previousWillChange.value, previousWillChange.priority);
54932
- else rootElement.style.removeProperty("will-change");
54933
- root.getBoundingClientRect();
54934
- if (previousTransition.value) rootElement.style.setProperty("transition", previousTransition.value, previousTransition.priority);
54935
- else rootElement.style.removeProperty("transition");
54936
- }
54937
- } catch {}
54938
- let rootToken = null;
54939
- if (maskToken) try {
54940
- const existing = root.getAttribute("data-stagehand-mask-root");
54941
- if (existing && existing.startsWith(maskToken)) rootToken = existing;
54942
- else {
54943
- rootToken = maskToken + "_root_" + Math.random().toString(36).slice(2);
54944
- root.setAttribute("data-stagehand-mask-root", rootToken);
54945
- }
54946
- } catch {
54947
- rootToken = null;
54948
- }
54949
- return {
54950
- ...localRect,
54951
- rootToken,
54952
- position: style.position === "fixed" ? "fixed" : "absolute"
54953
- };
54954
- }
54955
- return {
54956
- x: rect.left + window.scrollX,
54957
- y: rect.top + window.scrollY,
54958
- width: rect.width,
54959
- height: rect.height,
54960
- rootToken: null
54961
- };
54962
- }
54963
- //#endregion
54964
- //#region understudy/screenshotUtils.ts
54965
- function collectFramesForScreenshot(page) {
54966
- const seen = /* @__PURE__ */ new Map();
54967
- const main = page.mainFrame();
54968
- seen.set(main.frameId, main);
54969
- for (const frame of page.frames()) seen.set(frame.frameId, frame);
54970
- return Array.from(seen.values());
54971
- }
54972
- function normalizeScreenshotClip(clip) {
54973
- const x = Number(clip.x);
54974
- const y = Number(clip.y);
54975
- const width = Number(clip.width);
54976
- const height = Number(clip.height);
54977
- for (const [key, value] of Object.entries({
54978
- x,
54979
- y,
54980
- width,
54981
- height
54982
- })) if (!Number.isFinite(value)) throw new RangeError(`screenshot: clip.${key} must be a finite number`);
54983
- if (width <= 0 || height <= 0) throw new RangeError("screenshot: clip width/height must be positive");
54984
- return {
54985
- x,
54986
- y,
54987
- width,
54988
- height
54989
- };
54990
- }
54991
- async function computeScreenshotScale(page, mode) {
54992
- if (mode !== "css") return void 0;
54993
- try {
54994
- const dpr = await page.mainFrame().evaluate(() => {
54995
- const ratio = Number(window.devicePixelRatio || 1);
54996
- return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
54997
- }).catch(() => 1);
54998
- return Math.min(2, Math.max(.1, 1 / (Number.isFinite(dpr) && dpr > 0 ? dpr : 1)));
54999
- } catch {
55000
- return 1;
55001
- }
55002
- }
55003
- async function setTransparentBackground(session) {
55004
- await session.send("Emulation.setDefaultBackgroundColorOverride", { color: {
55005
- r: 0,
55006
- g: 0,
55007
- b: 0,
55008
- a: 0
55009
- } }).catch(() => {});
55010
- return async () => {
55011
- await session.send("Emulation.setDefaultBackgroundColorOverride", {}).catch(() => {});
55012
- };
55013
- }
55014
- async function applyStyleToFrames(frames, css, label) {
55015
- const trimmed = css.trim();
55016
- if (!trimmed) return async () => {};
55017
- const token = `__v3_style_${label}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
55018
- await Promise.all(frames.map((frame) => frame.evaluate(({ css, token }) => {
55019
- try {
55020
- const doc = document;
55021
- if (!doc) return;
55022
- const style = doc.createElement("style");
55023
- style.setAttribute("data-stagehand-style", token);
55024
- style.textContent = css;
55025
- (doc.head || doc.documentElement || doc.body)?.appendChild(style);
55026
- } catch {}
55027
- }, {
55028
- css: trimmed,
55029
- token
55030
- }).catch(() => {})));
55031
- return async () => {
55032
- await Promise.all(frames.map((frame) => frame.evaluate((token) => {
55033
- try {
55034
- const doc = document;
55035
- if (!doc) return;
55036
- doc.querySelectorAll(`[data-stagehand-style="${token}"]`).forEach((node) => node.remove());
55037
- } catch {}
55038
- }, token).catch(() => {})));
55039
- };
55040
- }
55041
- async function disableAnimations(frames) {
55042
- const cleanup = await applyStyleToFrames(frames, `
55043
- *,
55044
- *::before,
55045
- *::after {
55046
- animation-delay: 0s !important;
55047
- animation-duration: 0s !important;
55048
- animation-iteration-count: 1 !important;
55049
- animation-play-state: paused !important;
55050
- transition-property: none !important;
55051
- transition-duration: 0s !important;
55052
- transition-delay: 0s !important;
55053
- }`, "animations");
55054
- await Promise.all(frames.map((frame) => frame.evaluate(() => {
55055
- try {
55056
- const animations = typeof document.getAnimations === "function" ? document.getAnimations() : [];
55057
- for (const animation of animations) try {
55058
- const details = animation.effect?.getComputedTiming?.();
55059
- if (details && details.iterations !== Infinity) animation.finish?.();
55060
- else animation.cancel?.();
55061
- } catch {
55062
- animation.cancel?.();
55063
- }
55064
- } catch {}
55065
- }).catch(() => {})));
55066
- return cleanup;
55067
- }
55068
- async function hideCaret(frames) {
55069
- return applyStyleToFrames(frames, `
55070
- input,
55071
- textarea,
55072
- [contenteditable],
55073
- [contenteditable=""],
55074
- [contenteditable="true"],
55075
- [contenteditable="plaintext-only"],
55076
- *:focus {
55077
- caret-color: transparent !important;
55078
- }`, "caret");
55079
- }
55080
- async function applyMaskOverlays(locators, color) {
55081
- const rectsByFrame = /* @__PURE__ */ new Map();
55082
- const token = `__v3_mask_${Date.now()}_${Math.random().toString(36).slice(2)}`;
55083
- for (const locator of locators) try {
55084
- const info = await resolveMaskRects("real" in locator ? await locator.real() : locator, token);
55085
- if (!info) continue;
55086
- const entry = rectsByFrame.get(info.frame) ?? {
55087
- rects: [],
55088
- rootTokens: /* @__PURE__ */ new Set()
55089
- };
55090
- entry.rects.push(...info.rects);
55091
- for (const rect of info.rects) if (rect.rootToken) entry.rootTokens.add(rect.rootToken);
55092
- rectsByFrame.set(info.frame, entry);
55093
- } catch {}
55094
- if (rectsByFrame.size === 0) return async () => {};
55095
- await Promise.all(Array.from(rectsByFrame.entries()).map(([frame, { rects }]) => frame.evaluate(({ rects, color, token }) => {
55096
- try {
55097
- const doc = document;
55098
- if (!doc) return;
55099
- for (const rect of rects) {
55100
- const defaultRoot = doc.documentElement || doc.body;
55101
- if (!defaultRoot) return;
55102
- const root = rect.rootToken ? doc.querySelector(`[data-stagehand-mask-root="${rect.rootToken}"]`) || defaultRoot : defaultRoot;
55103
- if (!root) continue;
55104
- if (rect.rootToken) try {
55105
- const style = window.getComputedStyle(root);
55106
- if (style && style.position === "static") {
55107
- const rootEl = root;
55108
- if (!rootEl.hasAttribute("data-stagehand-mask-root-pos")) rootEl.setAttribute("data-stagehand-mask-root-pos", rootEl.style.position || "");
55109
- rootEl.style.position = "relative";
55110
- }
55111
- } catch {}
55112
- const el = doc.createElement("div");
55113
- el.setAttribute("data-stagehand-mask", token);
55114
- el.style.position = rect.position ?? "absolute";
55115
- el.style.left = `${rect.x}px`;
55116
- el.style.top = `${rect.y}px`;
55117
- el.style.width = `${rect.width}px`;
55118
- el.style.height = `${rect.height}px`;
55119
- el.style.backgroundColor = color;
55120
- el.style.pointerEvents = "none";
55121
- el.style.zIndex = "2147483647";
55122
- el.style.opacity = "1";
55123
- el.style.mixBlendMode = "normal";
55124
- root.appendChild(el);
55125
- }
55126
- } catch {}
55127
- }, {
55128
- rects,
55129
- color,
55130
- token
55131
- }).catch(() => {})));
55132
- await new Promise((resolve) => setTimeout(resolve, 100));
55133
- return async () => {
55134
- await Promise.all(Array.from(rectsByFrame.entries()).map(([frame, { rootTokens }]) => frame.evaluate(({ token, rootTokens }) => {
55135
- try {
55136
- const doc = document;
55137
- if (!doc) return;
55138
- doc.querySelectorAll(`[data-stagehand-mask="${token}"]`).forEach((node) => node.remove());
55139
- for (const rootToken of rootTokens) {
55140
- const root = doc.querySelector(`[data-stagehand-mask-root="${rootToken}"]`);
55141
- if (!root) continue;
55142
- const prev = root.getAttribute("data-stagehand-mask-root-pos");
55143
- if (prev !== null) {
55144
- root.style.position = prev;
55145
- root.removeAttribute("data-stagehand-mask-root-pos");
55146
- }
55147
- root.removeAttribute("data-stagehand-mask-root");
55148
- }
55149
- } catch {}
55150
- }, {
55151
- token,
55152
- rootTokens: Array.from(rootTokens)
55153
- }).catch(() => {})));
55154
- };
55155
- }
55156
- async function resolveMaskRects(locator, maskToken) {
55157
- const frame = locator.getFrame();
55158
- const session = frame.session;
55159
- try {
55160
- const resolved = await locator.resolveNodesForMask();
55161
- const rects = [];
55162
- for (const { objectId } of resolved) try {
55163
- const rect = await resolveMaskRectForObject(session, objectId, maskToken);
55164
- if (rect) rects.push(rect);
55165
- } catch {} finally {
55166
- await session.send("Runtime.releaseObject", { objectId }).catch(() => {});
55167
- }
55168
- if (!rects.length) return null;
55169
- return {
55170
- frame,
55171
- rects
55172
- };
55173
- } catch {
55174
- return null;
55175
- }
55176
- }
55177
- async function resolveMaskRectForObject(session, objectId, maskToken) {
55178
- const result = await session.send("Runtime.callFunctionOn", {
55179
- objectId,
55180
- functionDeclaration: resolveMaskRect.toString(),
55181
- arguments: [{ value: maskToken }],
55182
- returnByValue: true
55183
- });
55184
- if (result.exceptionDetails) return null;
55185
- const rect = result.result.value;
55186
- if (!rect) return null;
55187
- const { x, y, width, height } = rect;
55188
- if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) return null;
55189
- return {
55190
- x,
55191
- y,
55192
- width,
55193
- height,
55194
- rootToken: rect.rootToken && typeof rect.rootToken === "string" ? rect.rootToken : void 0,
55195
- position: rect.position === "fixed" ? "fixed" : "absolute"
55196
- };
55197
- }
55198
- async function runScreenshotCleanups(cleanups) {
55199
- for (let i = cleanups.length - 1; i >= 0; i -= 1) {
55200
- const fn = cleanups[i];
55201
- if (!fn) continue;
55202
- try {
55203
- const result = fn();
55204
- if (result && typeof result.then === "function") await result;
55205
- } catch {}
55206
- }
55207
- }
55208
- //#endregion
55209
- //#region timeoutConfig.ts
55210
- async function withTimeout(promise, timeout, operation) {
55211
- if (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0) return await promise;
55212
- let timeoutId;
55213
- const timeoutPromise = new Promise((_, reject) => {
55214
- timeoutId = setTimeout(() => {
55215
- reject(new TimeoutError(operation, timeout));
55216
- }, timeout);
55217
- });
55218
- try {
55219
- return await Promise.race([promise, timeoutPromise]);
55220
- } finally {
55221
- if (timeoutId) clearTimeout(timeoutId);
55222
- }
55223
- }
55224
- //#endregion
55225
55326
  //#region understudy/page.ts
55226
55327
  /**
55227
55328
  * Page
@@ -56018,28 +56119,44 @@ var Page = class Page {
56018
56119
  const scaleMode = opts.scale ?? "device";
56019
56120
  const frames = collectFramesForScreenshot(this);
56020
56121
  const clip = opts.clip ? normalizeScreenshotClip(opts.clip) : void 0;
56021
- const captureScale = await computeScreenshotScale(this, scaleMode);
56022
56122
  const maskLocators = opts.mask ?? [];
56023
56123
  const cleanupTasks = [];
56024
- const exec = async () => {
56124
+ const exec = async (signal) => {
56025
56125
  try {
56026
- if (opts.omitBackground) cleanupTasks.push(await setTransparentBackground(this.mainSession));
56027
- if (animationsMode === "disabled") cleanupTasks.push(await disableAnimations(frames));
56028
- if (caretMode === "hide") cleanupTasks.push(await hideCaret(frames));
56029
- if (opts.style && opts.style.trim()) cleanupTasks.push(await applyStyleToFrames(frames, opts.style, "custom"));
56030
- if (maskLocators.length > 0) cleanupTasks.push(await applyMaskOverlays(maskLocators, opts.maskColor ?? "#FF00FF"));
56031
- return await this.mainFrameWrapper.screenshot({
56126
+ const captureScale = await waitForScreenshot(computeScreenshotScale(this, scaleMode), signal);
56127
+ if (opts.omitBackground) {
56128
+ signal.throwIfAborted();
56129
+ cleanupTasks.push(await setTransparentBackground(this.mainSession));
56130
+ }
56131
+ if (animationsMode === "disabled") {
56132
+ signal.throwIfAborted();
56133
+ cleanupTasks.push(await disableAnimations(frames));
56134
+ }
56135
+ if (caretMode === "hide") {
56136
+ signal.throwIfAborted();
56137
+ cleanupTasks.push(await hideCaret(frames));
56138
+ }
56139
+ if (opts.style && opts.style.trim()) {
56140
+ signal.throwIfAborted();
56141
+ cleanupTasks.push(await applyStyleToFrames(frames, opts.style, "custom"));
56142
+ }
56143
+ if (maskLocators.length > 0) {
56144
+ signal.throwIfAborted();
56145
+ cleanupTasks.push(await applyMaskOverlays(maskLocators, opts.maskColor ?? "#FF00FF"));
56146
+ }
56147
+ return await waitForScreenshot(withScreenshotLock(this.conn, () => this.mainFrameWrapper.screenshot({
56032
56148
  fullPage: opts.fullPage,
56033
56149
  clip,
56034
56150
  type,
56035
56151
  quality: type === "jpeg" ? opts.quality : void 0,
56036
- scale: captureScale
56037
- });
56152
+ scale: captureScale,
56153
+ signal
56154
+ }), void 0), signal);
56038
56155
  } finally {
56039
56156
  await runScreenshotCleanups(cleanupTasks);
56040
56157
  }
56041
56158
  };
56042
- return await withTimeout(exec(), opts.timeout, "screenshot");
56159
+ return await withScreenshotLock(this, exec, opts.timeout);
56043
56160
  }
56044
56161
  /**
56045
56162
  * specifies additional HTTP headers to be included in every request sent by
@@ -56162,6 +56279,10 @@ var Page = class Page {
56162
56279
  ]);
56163
56280
  return targetFrame.evaluateInLocatorWorld(expression);
56164
56281
  }
56282
+ /** Internal batch evaluation; page.evaluate continues to use the main world unchanged. */
56283
+ async evaluateWithShadowRoots(functionSource) {
56284
+ return evaluateWithShadowRoots(this.mainSession, (expression) => this.evaluate(expression), functionSource);
56285
+ }
56165
56286
  /**
56166
56287
  * Evaluate a function or expression in the current main frame's main world.
56167
56288
  * - If a string is provided, it is treated as a JS expression.
@@ -57259,6 +57380,12 @@ var StagehandRuntime = class {
57259
57380
  await this.resolvePage(params.pageId).keyPress(params.key, params.options);
57260
57381
  return { ok: true };
57261
57382
  }
57383
+ async evaluateWithShadowRoots(pageId, functionSource) {
57384
+ const page = this.resolvePage(pageId);
57385
+ this.logger.debug("page.evaluateWithShadowRoots", { pageId });
57386
+ if (!page.evaluateWithShadowRoots) throw new ShadowRootEvaluationUnavailableError();
57387
+ return page.evaluateWithShadowRoots(functionSource);
57388
+ }
57262
57389
  async pageEvaluate(params) {
57263
57390
  const value = await this.resolvePage(params.pageId).evaluate(params.expression);
57264
57391
  return { value: value === void 0 ? null : value };