@browserbasehq/orca 3.0.9-alpha-4 → 3.1.0-patch.0

package/dist/esm/lib/v3/understudy/screenshotUtils.js

@@ -0,0 +1,352 @@
+import { StagehandInvalidArgumentError } from "../types/public/sdkErrors.js";
+import { screenshotScriptSources } from "../dom/build/screenshotScripts.generated.js";
+export function collectFramesForScreenshot(page) {
+    const seen = 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());
+}
+export 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 StagehandInvalidArgumentError(`screenshot: clip.${key} must be a finite number`);
+        }
+    }
+    if (width <= 0 || height <= 0) {
+        throw new StagehandInvalidArgumentError("screenshot: clip width/height must be positive");
+    }
+    return { x, y, width, height };
+}
+export async function computeScreenshotScale(page, mode) {
+    if (mode !== "css")
+        return undefined;
+    try {
+        const frame = page.mainFrame();
+        const dpr = await frame
+            .evaluate(() => {
+            const ratio = Number(window.devicePixelRatio || 1);
+            return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+        })
+            .catch(() => 1);
+        const safeRatio = Number.isFinite(dpr) && dpr > 0 ? dpr : 1;
+        return Math.min(2, Math.max(0.1, 1 / safeRatio));
+    }
+    catch {
+        return 1;
+    }
+}
+export 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(() => { });
+    };
+}
+export 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;
+            const parent = doc.head || doc.documentElement || doc.body;
+            parent?.appendChild(style);
+        }
+        catch {
+            // ignore
+        }
+    }, { css: trimmed, token })
+        .catch(() => { })));
+    return async () => {
+        await Promise.all(frames.map((frame) => frame
+            .evaluate((token) => {
+            try {
+                const doc = document;
+                if (!doc)
+                    return;
+                const nodes = doc.querySelectorAll(`[data-stagehand-style="${token}"]`);
+                nodes.forEach((node) => node.remove());
+            }
+            catch {
+                // ignore
+            }
+        }, token)
+            .catch(() => { })));
+    };
+}
+export async function disableAnimations(frames) {
+    const css = `
+*,
+*::before,
+*::after {
+  animation-delay: 0s !important;
+  animation-duration: 0s !important;
+  animation-iteration-count: 1 !important;
+  animation-play-state: paused !important;
+  transition-property: none !important;
+  transition-duration: 0s !important;
+  transition-delay: 0s !important;
+}`;
+    const cleanup = await applyStyleToFrames(frames, css, "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 {
+            // ignore
+        }
+    })
+        .catch(() => { })));
+    return cleanup;
+}
+export async function hideCaret(frames) {
+    const css = `
+input,
+textarea,
+[contenteditable],
+[contenteditable=""],
+[contenteditable="true"],
+[contenteditable="plaintext-only"],
+*:focus {
+  caret-color: transparent !important;
+}`;
+    return applyStyleToFrames(frames, css, "caret");
+}
+export async function applyMaskOverlays(locators, color) {
+    const rectsByFrame = new Map();
+    const token = `__v3_mask_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+    for (const locator of locators) {
+        try {
+            const info = await resolveMaskRects(locator, token);
+            if (!info)
+                continue;
+            const entry = rectsByFrame.get(info.frame) ?? {
+                rects: [],
+                rootTokens: 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 {
+            // ignore individual locator failures
+        }
+    }
+    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 {
+                        // ignore
+                    }
+                }
+                const el = doc.createElement("div");
+                el.setAttribute("data-stagehand-mask", token);
+                el.style.position = "absolute";
+                el.style.left = `${rect.x}px`;
+                el.style.top = `${rect.y}px`;
+                el.style.width = `${rect.width}px`;
+                el.style.height = `${rect.height}px`;
+                el.style.backgroundColor = color;
+                el.style.pointerEvents = "none";
+                el.style.zIndex = "2147483647";
+                el.style.opacity = "1";
+                el.style.mixBlendMode = "normal";
+                root.appendChild(el);
+            }
+        }
+        catch {
+            // ignore
+        }
+    }, { rects, color, token })
+        .catch(() => { })));
+    return async () => {
+        await Promise.all(Array.from(rectsByFrame.entries()).map(([frame, { rootTokens }]) => frame
+            .evaluate(({ token, rootTokens }) => {
+            try {
+                const doc = document;
+                if (!doc)
+                    return;
+                const nodes = doc.querySelectorAll(`[data-stagehand-mask="${token}"]`);
+                nodes.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 {
+                // ignore
+            }
+        }, { token, rootTokens: Array.from(rootTokens) })
+            .catch(() => { })));
+    };
+}
+async function resolveMaskRects(locator, maskToken) {
+    const frame = locator.getFrame();
+    const session = frame.session;
+    let resolved = [];
+    try {
+        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 {
+                // ignore individual element failures
+            }
+            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: screenshotScriptSources.resolveMaskRect,
+        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
+            : undefined,
+    };
+}
+export 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 {
+            // ignore cleanup errors
+        }
+    }
+}
+export async function withScreenshotTimeout(timeoutMs, task) {
+    if (!timeoutMs || timeoutMs <= 0)
+        return task();
+    let timer = null;
+    const timeoutPromise = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            reject(new Error(`screenshot: timeout of ${timeoutMs}ms exceeded`));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([task(), timeoutPromise]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=screenshotUtils.js.map

package/dist/esm/lib/v3/understudy/screenshotUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshotUtils.js","sourceRoot":"","sources":["../../../../../lib/v3/understudy/screenshotUtils.ts"],"names":[],"mappings":"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","sourcesContent":["import { Protocol } from \"devtools-protocol\";\nimport type { CDPSessionLike } from \"./cdp.js\";\nimport type { Frame } from \"./frame.js\";\nimport type { Locator } from \"./locator.js\";\nimport type { Page } from \"./page.js\";\nimport type {\n  ScreenshotClip,\n  ScreenshotScaleOption,\n} from \"../types/public/screenshotTypes.js\";\nimport { StagehandInvalidArgumentError } from \"../types/public/sdkErrors.js\";\nimport { screenshotScriptSources } from \"../dom/build/screenshotScripts.generated.js\";\n\nexport type ScreenshotCleanup = () => Promise<void> | void;\n\nexport function collectFramesForScreenshot(page: Page): Frame[] {\n  const seen = new Map<string, Frame>();\n  const main = page.mainFrame();\n  seen.set(main.frameId, main);\n  for (const frame of page.frames()) {\n    seen.set(frame.frameId, frame);\n  }\n  return Array.from(seen.values());\n}\n\nexport function normalizeScreenshotClip(clip: ScreenshotClip): ScreenshotClip {\n  const x = Number(clip.x);\n  const y = Number(clip.y);\n  const width = Number(clip.width);\n  const height = Number(clip.height);\n\n  for (const [key, value] of Object.entries({ x, y, width, height })) {\n    if (!Number.isFinite(value)) {\n      throw new StagehandInvalidArgumentError(\n        `screenshot: clip.${key} must be a finite number`,\n      );\n    }\n  }\n\n  if (width <= 0 || height <= 0) {\n    throw new StagehandInvalidArgumentError(\n      \"screenshot: clip width/height must be positive\",\n    );\n  }\n\n  return { x, y, width, height };\n}\n\nexport async function computeScreenshotScale(\n  page: Page,\n  mode: ScreenshotScaleOption,\n): Promise<number | undefined> {\n  if (mode !== \"css\") return undefined;\n  try {\n    const frame = page.mainFrame();\n    const dpr = await frame\n      .evaluate(() => {\n        const ratio = Number(window.devicePixelRatio || 1);\n        return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;\n      })\n      .catch(() => 1);\n    const safeRatio = Number.isFinite(dpr) && dpr > 0 ? dpr : 1;\n    return Math.min(2, Math.max(0.1, 1 / safeRatio));\n  } catch {\n    return 1;\n  }\n}\n\nexport async function setTransparentBackground(\n  session: CDPSessionLike,\n): Promise<ScreenshotCleanup> {\n  await session\n    .send(\"Emulation.setDefaultBackgroundColorOverride\", {\n      color: { r: 0, g: 0, b: 0, a: 0 },\n    })\n    .catch(() => {});\n\n  return async () => {\n    await session\n      .send(\"Emulation.setDefaultBackgroundColorOverride\", {})\n      .catch(() => {});\n  };\n}\n\nexport async function applyStyleToFrames(\n  frames: Frame[],\n  css: string,\n  label: string,\n): Promise<ScreenshotCleanup> {\n  const trimmed = css.trim();\n  if (!trimmed) return async () => {};\n  const token = `__v3_style_${label}_${Date.now()}_${Math.random()\n    .toString(36)\n    .slice(2)}`;\n\n  await Promise.all(\n    frames.map((frame) =>\n      frame\n        .evaluate(\n          ({ css, token }) => {\n            try {\n              const doc = document;\n              if (!doc) return;\n              const style = doc.createElement(\"style\");\n              style.setAttribute(\"data-stagehand-style\", token);\n              style.textContent = css;\n              const parent = doc.head || doc.documentElement || doc.body;\n              parent?.appendChild(style);\n            } catch {\n              // ignore\n            }\n          },\n          { css: trimmed, token },\n        )\n        .catch(() => {}),\n    ),\n  );\n\n  return async () => {\n    await Promise.all(\n      frames.map((frame) =>\n        frame\n          .evaluate((token) => {\n            try {\n              const doc = document;\n              if (!doc) return;\n              const nodes = doc.querySelectorAll(\n                `[data-stagehand-style=\"${token}\"]`,\n              );\n              nodes.forEach((node) => node.remove());\n            } catch {\n              // ignore\n            }\n          }, token)\n          .catch(() => {}),\n      ),\n    );\n  };\n}\n\nexport async function disableAnimations(\n  frames: Frame[],\n): Promise<ScreenshotCleanup> {\n  const css = `\n*,\n*::before,\n*::after {\n  animation-delay: 0s !important;\n  animation-duration: 0s !important;\n  animation-iteration-count: 1 !important;\n  animation-play-state: paused !important;\n  transition-property: none !important;\n  transition-duration: 0s !important;\n  transition-delay: 0s !important;\n}`;\n\n  const cleanup = await applyStyleToFrames(frames, css, \"animations\");\n\n  await Promise.all(\n    frames.map((frame) =>\n      frame\n        .evaluate(() => {\n          try {\n            const animations =\n              typeof document.getAnimations === \"function\"\n                ? document.getAnimations()\n                : [];\n            for (const animation of animations) {\n              try {\n                const details = animation.effect?.getComputedTiming?.();\n                if (details && details.iterations !== Infinity) {\n                  animation.finish?.();\n                } else {\n                  animation.cancel?.();\n                }\n              } catch {\n                animation.cancel?.();\n              }\n            }\n          } catch {\n            // ignore\n          }\n        })\n        .catch(() => {}),\n    ),\n  );\n\n  return cleanup;\n}\n\nexport async function hideCaret(frames: Frame[]): Promise<ScreenshotCleanup> {\n  const css = `\ninput,\ntextarea,\n[contenteditable],\n[contenteditable=\"\"],\n[contenteditable=\"true\"],\n[contenteditable=\"plaintext-only\"],\n*:focus {\n  caret-color: transparent !important;\n}`;\n\n  return applyStyleToFrames(frames, css, \"caret\");\n}\n\nexport async function applyMaskOverlays(\n  locators: Locator[],\n  color: string,\n): Promise<ScreenshotCleanup> {\n  type MaskRectSpec = ScreenshotClip & { rootToken?: string | null };\n  const rectsByFrame = new Map<\n    Frame,\n    { rects: MaskRectSpec[]; rootTokens: Set<string> }\n  >();\n\n  const token = `__v3_mask_${Date.now()}_${Math.random().toString(36).slice(2)}`;\n\n  for (const locator of locators) {\n    try {\n      const info = await resolveMaskRects(locator, token);\n      if (!info) continue;\n      const entry = rectsByFrame.get(info.frame) ?? {\n        rects: [],\n        rootTokens: new Set<string>(),\n      };\n      entry.rects.push(...info.rects);\n      for (const rect of info.rects) {\n        if (rect.rootToken) entry.rootTokens.add(rect.rootToken);\n      }\n      rectsByFrame.set(info.frame, entry);\n    } catch {\n      // ignore individual locator failures\n    }\n  }\n\n  if (rectsByFrame.size === 0) {\n    return async () => {};\n  }\n\n  await Promise.all(\n    Array.from(rectsByFrame.entries()).map(([frame, { rects }]) =>\n      frame\n        .evaluate(\n          ({ rects, color, token }) => {\n            try {\n              const doc = document;\n              if (!doc) return;\n              for (const rect of rects) {\n                const defaultRoot = doc.documentElement || doc.body;\n                if (!defaultRoot) return;\n                const root = rect.rootToken\n                  ? doc.querySelector(\n                      `[data-stagehand-mask-root=\"${rect.rootToken}\"]`,\n                    ) || defaultRoot\n                  : defaultRoot;\n                if (!root) continue;\n                if (rect.rootToken) {\n                  try {\n                    const style = window.getComputedStyle(root as Element);\n                    if (style && style.position === \"static\") {\n                      const rootEl = root as HTMLElement;\n                      if (\n                        !rootEl.hasAttribute(\"data-stagehand-mask-root-pos\")\n                      ) {\n                        rootEl.setAttribute(\n                          \"data-stagehand-mask-root-pos\",\n                          rootEl.style.position || \"\",\n                        );\n                      }\n                      rootEl.style.position = \"relative\";\n                    }\n                  } catch {\n                    // ignore\n                  }\n                }\n                const el = doc.createElement(\"div\");\n                el.setAttribute(\"data-stagehand-mask\", token);\n                el.style.position = \"absolute\";\n                el.style.left = `${rect.x}px`;\n                el.style.top = `${rect.y}px`;\n                el.style.width = `${rect.width}px`;\n                el.style.height = `${rect.height}px`;\n                el.style.backgroundColor = color;\n                el.style.pointerEvents = \"none\";\n                el.style.zIndex = \"2147483647\";\n                el.style.opacity = \"1\";\n                el.style.mixBlendMode = \"normal\";\n                (root as Element).appendChild(el);\n              }\n            } catch {\n              // ignore\n            }\n          },\n          { rects, color, token },\n        )\n        .catch(() => {}),\n    ),\n  );\n\n  return async () => {\n    await Promise.all(\n      Array.from(rectsByFrame.entries()).map(([frame, { rootTokens }]) =>\n        frame\n          .evaluate(\n            ({ token, rootTokens }) => {\n              try {\n                const doc = document;\n                if (!doc) return;\n                const nodes = doc.querySelectorAll(\n                  `[data-stagehand-mask=\"${token}\"]`,\n                );\n                nodes.forEach((node) => node.remove());\n                for (const rootToken of rootTokens) {\n                  const root = doc.querySelector(\n                    `[data-stagehand-mask-root=\"${rootToken}\"]`,\n                  ) as HTMLElement | null;\n                  if (!root) continue;\n                  const prev = root.getAttribute(\n                    \"data-stagehand-mask-root-pos\",\n                  );\n                  if (prev !== null) {\n                    root.style.position = prev;\n                    root.removeAttribute(\"data-stagehand-mask-root-pos\");\n                  }\n                  root.removeAttribute(\"data-stagehand-mask-root\");\n                }\n              } catch {\n                // ignore\n              }\n            },\n            { token, rootTokens: Array.from(rootTokens) },\n          )\n          .catch(() => {}),\n      ),\n    );\n  };\n}\n\nasync function resolveMaskRects(\n  locator: Locator,\n  maskToken: string,\n): Promise<{\n  frame: Frame;\n  rects: Array<ScreenshotClip & { rootToken?: string | null }>;\n} | null> {\n  const frame = locator.getFrame();\n  const session = frame.session;\n  let resolved: Array<{\n    objectId: Protocol.Runtime.RemoteObjectId;\n    nodeId: Protocol.DOM.NodeId | null;\n  }> = [];\n\n  try {\n    resolved = await locator.resolveNodesForMask();\n    const rects: Array<ScreenshotClip & { rootToken?: string | null }> = [];\n\n    for (const { objectId } of resolved) {\n      try {\n        const rect = await resolveMaskRectForObject(\n          session,\n          objectId,\n          maskToken,\n        );\n        if (rect) rects.push(rect);\n      } catch {\n        // ignore individual element failures\n      } finally {\n        await session\n          .send<never>(\"Runtime.releaseObject\", { objectId })\n          .catch(() => {});\n      }\n    }\n\n    if (!rects.length) return null;\n\n    return { frame, rects };\n  } catch {\n    return null;\n  }\n}\n\nasync function resolveMaskRectForObject(\n  session: CDPSessionLike,\n  objectId: Protocol.Runtime.RemoteObjectId,\n  maskToken: string,\n): Promise<(ScreenshotClip & { rootToken?: string | null }) | null> {\n  const result = await session.send<Protocol.Runtime.CallFunctionOnResponse>(\n    \"Runtime.callFunctionOn\",\n    {\n      objectId,\n      functionDeclaration: screenshotScriptSources.resolveMaskRect,\n      arguments: [{ value: maskToken }],\n      returnByValue: true,\n    },\n  );\n\n  if (result.exceptionDetails) {\n    return null;\n  }\n\n  const rect = result.result.value as\n    | (ScreenshotClip & { rootToken?: string | null })\n    | null;\n  if (!rect) return null;\n\n  const { x, y, width, height } = rect;\n  if (\n    !Number.isFinite(x) ||\n    !Number.isFinite(y) ||\n    !Number.isFinite(width) ||\n    !Number.isFinite(height) ||\n    width <= 0 ||\n    height <= 0\n  ) {\n    return null;\n  }\n\n  return {\n    x,\n    y,\n    width,\n    height,\n    rootToken:\n      rect.rootToken && typeof rect.rootToken === \"string\"\n        ? rect.rootToken\n        : undefined,\n  };\n}\n\nexport async function runScreenshotCleanups(\n  cleanups: ScreenshotCleanup[],\n): Promise<void> {\n  for (let i = cleanups.length - 1; i >= 0; i -= 1) {\n    const fn = cleanups[i];\n    if (!fn) continue;\n    try {\n      const result = fn();\n      if (result && typeof (result as Promise<void>).then === \"function\") {\n        await result;\n      }\n    } catch {\n      // ignore cleanup errors\n    }\n  }\n}\n\nexport async function withScreenshotTimeout<T>(\n  timeoutMs: number | undefined,\n  task: () => Promise<T>,\n): Promise<T> {\n  if (!timeoutMs || timeoutMs <= 0) return task();\n\n  let timer: NodeJS.Timeout | null = null;\n  const timeoutPromise = new Promise<T>((_, reject) => {\n    timer = setTimeout(() => {\n      reject(new Error(`screenshot: timeout of ${timeoutMs}ms exceeded`));\n    }, timeoutMs);\n  });\n\n  try {\n    return await Promise.race([task(), timeoutPromise]);\n  } finally {\n    if (timer) clearTimeout(timer);\n  }\n}\n"]}

package/dist/esm/lib/v3/understudy/selectorResolver.d.ts

@@ -0,0 +1,38 @@
+import type { Protocol } from "devtools-protocol";
+import type { Frame } from "./frame.js";
+export type SelectorQuery = {
+    kind: "css";
+    value: string;
+} | {
+    kind: "text";
+    value: string;
+} | {
+    kind: "xpath";
+    value: string;
+};
+export interface ResolvedNode {
+    objectId: Protocol.Runtime.RemoteObjectId;
+    nodeId: Protocol.DOM.NodeId | null;
+}
+export interface ResolveManyOptions {
+    limit?: number;
+}
+export declare class FrameSelectorResolver {
+    private readonly frame;
+    constructor(frame: Frame);
+    static parseSelector(raw: string): SelectorQuery;
+    resolveFirst(query: SelectorQuery): Promise<ResolvedNode | null>;
+    resolveAll(query: SelectorQuery, { limit }?: ResolveManyOptions): Promise<ResolvedNode[]>;
+    count(query: SelectorQuery): Promise<number>;
+    resolveAtIndex(query: SelectorQuery, index: number): Promise<ResolvedNode | null>;
+    private buildLocatorInvocation;
+    private resolveCss;
+    private resolveText;
+    private resolveXPath;
+    private countCss;
+    private countText;
+    private countXPath;
+    private resolveFromObjectId;
+    private evaluateCount;
+    private evaluateElement;
+}