@vellumai/assistant 0.6.1 → 0.6.3

package/src/tools/browser/cdp-client/cdp-dom-helpers.ts

@@ -0,0 +1,695 @@
+/**
+ * Common CDP idioms that each browser tool would otherwise reimplement:
+ * selector resolution, mouse/keyboard dispatch, screenshot capture,
+ * navigation, polling waits, and small Runtime.evaluate wrappers.
+ *
+ * Every helper takes a {@link CdpClient} as its first argument, forwards
+ * an optional {@link AbortSignal} verbatim to `CdpClient.send`, and
+ * throws a {@link CdpError} on failure. The module is pure plumbing —
+ * no I/O beyond the injected CdpClient — which keeps it trivial to
+ * unit-test against a fake in-memory client.
+ */
+
+import { CdpError } from "./errors.js";
+import type { CdpClient } from "./types.js";
+
+// ── Selector / node resolution ────────────────────────────────────────
+
+/**
+ * Resolve a CSS selector to a CDP `backendNodeId`. Runs
+ * `DOM.getDocument` → `DOM.querySelector` → `DOM.describeNode` and
+ * throws {@link CdpError} with `code: "cdp_error"` if no element
+ * matches (CDP signals this by returning `nodeId: 0`).
+ */
+export async function querySelectorBackendNodeId(
+  cdp: CdpClient,
+  selector: string,
+  signal?: AbortSignal,
+): Promise<number> {
+  const { root } = await cdp.send<{ root: { nodeId: number } }>(
+    "DOM.getDocument",
+    {},
+    signal,
+  );
+  const { nodeId } = await cdp.send<{ nodeId: number }>(
+    "DOM.querySelector",
+    { nodeId: root.nodeId, selector },
+    signal,
+  );
+  if (!nodeId) {
+    throw new CdpError("cdp_error", `Element not found: ${selector}`, {
+      cdpMethod: "DOM.querySelector",
+      cdpParams: { selector },
+    });
+  }
+  const { node } = await cdp.send<{ node: { backendNodeId: number } }>(
+    "DOM.describeNode",
+    { nodeId, depth: 0 },
+    signal,
+  );
+  return node.backendNodeId;
+}
+
+/** Scroll the element identified by `backendNodeId` into view if needed. */
+export async function scrollIntoViewIfNeeded(
+  cdp: CdpClient,
+  backendNodeId: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  await cdp.send("DOM.scrollIntoViewIfNeeded", { backendNodeId }, signal);
+}
+
+/**
+ * Read the element's content-quad via `DOM.getBoxModel` and return the
+ * midpoint in viewport coordinates. CDP returns `content` as a flat
+ * 8-number array `[x1,y1, x2,y2, x3,y3, x4,y4]`.
+ */
+export async function getCenterPoint(
+  cdp: CdpClient,
+  backendNodeId: number,
+  signal?: AbortSignal,
+): Promise<{ x: number; y: number }> {
+  const { model } = await cdp.send<{
+    model: { content: number[] };
+  }>("DOM.getBoxModel", { backendNodeId }, signal);
+  const xs = [
+    model.content[0]!,
+    model.content[2]!,
+    model.content[4]!,
+    model.content[6]!,
+  ];
+  const ys = [
+    model.content[1]!,
+    model.content[3]!,
+    model.content[5]!,
+    model.content[7]!,
+  ];
+  return {
+    x: (Math.min(...xs) + Math.max(...xs)) / 2,
+    y: (Math.min(...ys) + Math.max(...ys)) / 2,
+  };
+}
+
+/** Focus an element by `backendNodeId` via `DOM.focus`. */
+export async function focusElement(
+  cdp: CdpClient,
+  backendNodeId: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  await cdp.send("DOM.focus", { backendNodeId }, signal);
+}
+
+// ── Mouse / keyboard / wheel dispatch ─────────────────────────────────
+
+/**
+ * Dispatch a full left-click (mouseMoved + mousePressed + mouseReleased)
+ * at the given viewport point.
+ */
+export async function dispatchClickAt(
+  cdp: CdpClient,
+  point: { x: number; y: number },
+  signal?: AbortSignal,
+): Promise<void> {
+  const base = { x: point.x, y: point.y, button: "left", clickCount: 1 };
+  await cdp.send(
+    "Input.dispatchMouseEvent",
+    { ...base, type: "mouseMoved" },
+    signal,
+  );
+  await cdp.send(
+    "Input.dispatchMouseEvent",
+    { ...base, type: "mousePressed" },
+    signal,
+  );
+  await cdp.send(
+    "Input.dispatchMouseEvent",
+    { ...base, type: "mouseReleased" },
+    signal,
+  );
+}
+
+/** Dispatch a single mouseMoved (hover) at the given viewport point. */
+export async function dispatchHoverAt(
+  cdp: CdpClient,
+  point: { x: number; y: number },
+  signal?: AbortSignal,
+): Promise<void> {
+  await cdp.send(
+    "Input.dispatchMouseEvent",
+    { type: "mouseMoved", x: point.x, y: point.y, button: "none" },
+    signal,
+  );
+}
+
+/**
+ * Insert text at the currently focused element via `Input.insertText`.
+ * Unlike synthesizing individual key events, this dispatches the right
+ * `input`/`change` events that form controls expect.
+ */
+export async function dispatchInsertText(
+  cdp: CdpClient,
+  text: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  await cdp.send("Input.insertText", { text }, signal);
+}
+
+/**
+ * Per-key descriptor used by {@link dispatchKeyPress}. Mirrors the
+ * fields CDP's `Input.dispatchKeyEvent` accepts. `text` is set only
+ * for printable keys (so we know to also dispatch a `char` event).
+ */
+interface KeyDescriptor {
+  key: string;
+  code: string;
+  windowsVirtualKeyCode: number;
+  text?: string;
+}
+
+/**
+ * Subset of the US keyboard layout used to populate
+ * `Input.dispatchKeyEvent` params. Without these fields, sites that
+ * read `event.keyCode` (e.g. `event.keyCode === 13` for Enter) or
+ * `event.code` see zeros and the press is silently ignored.
+ *
+ * Single-character keys (a-z, A-Z, 0-9) are resolved dynamically by
+ * {@link resolveKeyDescriptor} to keep the static map small.
+ */
+const KEY_DESCRIPTORS: Record<string, KeyDescriptor> = {
+  Enter: {
+    key: "Enter",
+    code: "Enter",
+    windowsVirtualKeyCode: 13,
+    text: "\r",
+  },
+  Tab: { key: "Tab", code: "Tab", windowsVirtualKeyCode: 9, text: "\t" },
+  Escape: { key: "Escape", code: "Escape", windowsVirtualKeyCode: 27 },
+  Backspace: {
+    key: "Backspace",
+    code: "Backspace",
+    windowsVirtualKeyCode: 8,
+  },
+  Delete: { key: "Delete", code: "Delete", windowsVirtualKeyCode: 46 },
+  Insert: { key: "Insert", code: "Insert", windowsVirtualKeyCode: 45 },
+  ArrowUp: { key: "ArrowUp", code: "ArrowUp", windowsVirtualKeyCode: 38 },
+  ArrowDown: {
+    key: "ArrowDown",
+    code: "ArrowDown",
+    windowsVirtualKeyCode: 40,
+  },
+  ArrowLeft: {
+    key: "ArrowLeft",
+    code: "ArrowLeft",
+    windowsVirtualKeyCode: 37,
+  },
+  ArrowRight: {
+    key: "ArrowRight",
+    code: "ArrowRight",
+    windowsVirtualKeyCode: 39,
+  },
+  // Navigation keys. Sites commonly check `event.keyCode` for these
+  // (PageDown = 34 to scroll a page, Home = 36 to jump to top, etc.)
+  // so omitting `code`/`windowsVirtualKeyCode` makes the press a
+  // silent no-op on those handlers.
+  Home: { key: "Home", code: "Home", windowsVirtualKeyCode: 36 },
+  End: { key: "End", code: "End", windowsVirtualKeyCode: 35 },
+  PageUp: { key: "PageUp", code: "PageUp", windowsVirtualKeyCode: 33 },
+  PageDown: { key: "PageDown", code: "PageDown", windowsVirtualKeyCode: 34 },
+  // Space is special: Playwright callers use "Space" as the key name
+  // but `event.key` is actually " ". Accept both spellings so either
+  // calling convention works, and always emit `code: "Space"` +
+  // `windowsVirtualKeyCode: 32` so Space-to-activate / Space-to-scroll
+  // handlers fire correctly.
+  Space: { key: " ", code: "Space", windowsVirtualKeyCode: 32, text: " " },
+  " ": { key: " ", code: "Space", windowsVirtualKeyCode: 32, text: " " },
+  // Function keys (F1-F12). Virtual key codes 112-123 per the Windows
+  // input API. `resolveKeyDescriptor` cannot derive these dynamically
+  // because they are multi-character names with no 1:1 char mapping.
+  F1: { key: "F1", code: "F1", windowsVirtualKeyCode: 112 },
+  F2: { key: "F2", code: "F2", windowsVirtualKeyCode: 113 },
+  F3: { key: "F3", code: "F3", windowsVirtualKeyCode: 114 },
+  F4: { key: "F4", code: "F4", windowsVirtualKeyCode: 115 },
+  F5: { key: "F5", code: "F5", windowsVirtualKeyCode: 116 },
+  F6: { key: "F6", code: "F6", windowsVirtualKeyCode: 117 },
+  F7: { key: "F7", code: "F7", windowsVirtualKeyCode: 118 },
+  F8: { key: "F8", code: "F8", windowsVirtualKeyCode: 119 },
+  F9: { key: "F9", code: "F9", windowsVirtualKeyCode: 120 },
+  F10: { key: "F10", code: "F10", windowsVirtualKeyCode: 121 },
+  F11: { key: "F11", code: "F11", windowsVirtualKeyCode: 122 },
+  F12: { key: "F12", code: "F12", windowsVirtualKeyCode: 123 },
+};
+
+/**
+ * Resolve a key name into a {@link KeyDescriptor}. Single-character
+ * keys (a-z, A-Z, 0-9) are computed on demand: `code` is `KeyA`/
+ * `Digit0`/etc., `windowsVirtualKeyCode` is the uppercase ASCII code,
+ * and `text` is the literal character. Returns `null` for unknown
+ * multi-character keys so callers can fall back to a minimal event.
+ */
+function resolveKeyDescriptor(key: string): KeyDescriptor | null {
+  const fromMap = KEY_DESCRIPTORS[key];
+  if (fromMap) return fromMap;
+  if (key.length !== 1) return null;
+  const charCode = key.charCodeAt(0);
+  // a-z / A-Z
+  if (
+    (charCode >= 65 && charCode <= 90) ||
+    (charCode >= 97 && charCode <= 122)
+  ) {
+    const upper = key.toUpperCase();
+    return {
+      key,
+      code: `Key${upper}`,
+      windowsVirtualKeyCode: upper.charCodeAt(0),
+      text: key,
+    };
+  }
+  // 0-9
+  if (charCode >= 48 && charCode <= 57) {
+    return {
+      key,
+      code: `Digit${key}`,
+      windowsVirtualKeyCode: charCode,
+      text: key,
+    };
+  }
+  // Other printable ASCII (space, punctuation): still emit text + the
+  // raw char code so sites that check `event.key` and `event.charCode`
+  // see something sensible.
+  if (charCode >= 32 && charCode <= 126) {
+    return {
+      key,
+      code: "",
+      windowsVirtualKeyCode: charCode,
+      text: key,
+    };
+  }
+  return null;
+}
+
+/**
+ * Press a single key (keyDown + optional `char` + keyUp). Resolves
+ * the key name to a {@link KeyDescriptor} so CDP receives the right
+ * `code` / `windowsVirtualKeyCode` / `text` fields — required by
+ * sites that check `event.keyCode` (e.g. Enter-to-submit) or
+ * `event.code`. For printable keys we also dispatch a `char` event
+ * between keyDown and keyUp so the character is actually inserted
+ * into focused inputs.
+ */
+export async function dispatchKeyPress(
+  cdp: CdpClient,
+  key: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const desc = resolveKeyDescriptor(key);
+  if (!desc) {
+    // Unknown multi-character key (e.g. F-keys we have not mapped).
+    // Fall back to the minimal payload so callers still see a
+    // keyDown/keyUp pair, and warn so we can extend the map.
+
+    console.warn(
+      `dispatchKeyPress: no descriptor for key "${key}", sending minimal event`,
+    );
+    await cdp.send("Input.dispatchKeyEvent", { type: "keyDown", key }, signal);
+    await cdp.send("Input.dispatchKeyEvent", { type: "keyUp", key }, signal);
+    return;
+  }
+
+  const baseParams: Record<string, unknown> = {
+    key: desc.key,
+    code: desc.code,
+    windowsVirtualKeyCode: desc.windowsVirtualKeyCode,
+  };
+  if (desc.text !== undefined) {
+    baseParams.text = desc.text;
+  }
+
+  await cdp.send(
+    "Input.dispatchKeyEvent",
+    { ...baseParams, type: "keyDown" },
+    signal,
+  );
+  if (desc.text !== undefined) {
+    await cdp.send(
+      "Input.dispatchKeyEvent",
+      { ...baseParams, type: "char" },
+      signal,
+    );
+  }
+  await cdp.send(
+    "Input.dispatchKeyEvent",
+    { ...baseParams, type: "keyUp" },
+    signal,
+  );
+}
+
+/** Dispatch a wheel scroll delta at the given viewport point. */
+export async function dispatchWheelScroll(
+  cdp: CdpClient,
+  point: { x: number; y: number },
+  delta: { deltaX: number; deltaY: number },
+  signal?: AbortSignal,
+): Promise<void> {
+  await cdp.send(
+    "Input.dispatchMouseEvent",
+    {
+      type: "mouseWheel",
+      x: point.x,
+      y: point.y,
+      deltaX: delta.deltaX,
+      deltaY: delta.deltaY,
+    },
+    signal,
+  );
+}
+
+// ── Runtime.evaluate wrappers ─────────────────────────────────────────
+
+/** Get the current page URL via `Runtime.evaluate("document.location.href")`. */
+export async function getCurrentUrl(
+  cdp: CdpClient,
+  signal?: AbortSignal,
+): Promise<string> {
+  const { result } = await cdp.send<{ result: { value: string } }>(
+    "Runtime.evaluate",
+    { expression: "document.location.href", returnByValue: true },
+    signal,
+  );
+  return result.value;
+}
+
+/** Get the current page title via `Runtime.evaluate("document.title")`. */
+export async function getPageTitle(
+  cdp: CdpClient,
+  signal?: AbortSignal,
+): Promise<string> {
+  const { result } = await cdp.send<{ result: { value: string } }>(
+    "Runtime.evaluate",
+    { expression: "document.title", returnByValue: true },
+    signal,
+  );
+  return result.value ?? "";
+}
+
+/**
+ * Evaluate a JS expression via `Runtime.evaluate` and return the
+ * deserialized value. Throws {@link CdpError} with `code: "cdp_error"`
+ * if the expression threw (surfaced via CDP's `exceptionDetails`).
+ *
+ * Defaults: `returnByValue: true`, `awaitPromise: true`, `userGesture: true`.
+ */
+export async function evaluateExpression<T = unknown>(
+  cdp: CdpClient,
+  expression: string,
+  opts?: { awaitPromise?: boolean },
+  signal?: AbortSignal,
+): Promise<T> {
+  const res = await cdp.send<{
+    result: { value: T };
+    exceptionDetails?: {
+      text?: string;
+      exception?: { description?: string };
+    };
+  }>(
+    "Runtime.evaluate",
+    {
+      expression,
+      returnByValue: true,
+      awaitPromise: opts?.awaitPromise ?? true,
+      userGesture: true,
+    },
+    signal,
+  );
+  if (res.exceptionDetails) {
+    const msg =
+      res.exceptionDetails.exception?.description ??
+      res.exceptionDetails.text ??
+      "Runtime.evaluate exception";
+    throw new CdpError("cdp_error", msg, {
+      cdpMethod: "Runtime.evaluate",
+      cdpParams: { expression },
+    });
+  }
+  return res.result.value;
+}
+
+// ── Screenshot ────────────────────────────────────────────────────────
+
+/**
+ * Capture a JPEG screenshot via `Page.captureScreenshot` and return the
+ * decoded bytes as a Node `Buffer`. Defaults to quality 80. Pass
+ * `fullPage: true` to capture beyond the viewport.
+ */
+export async function captureScreenshotJpeg(
+  cdp: CdpClient,
+  opts: { quality?: number; fullPage?: boolean } = {},
+  signal?: AbortSignal,
+): Promise<Buffer> {
+  const { data } = await cdp.send<{ data: string }>(
+    "Page.captureScreenshot",
+    {
+      format: "jpeg",
+      quality: opts.quality ?? 80,
+      captureBeyondViewport: opts.fullPage === true,
+    },
+    signal,
+  );
+  return Buffer.from(data, "base64");
+}
+
+// ── Navigation / waiting ──────────────────────────────────────────────
+
+/**
+ * Navigate to `url` and wait until the new document has committed
+ * (the URL has changed from the pre-navigation URL, or it's a
+ * same-URL reload) AND `document.readyState` has reached
+ * `interactive` or `complete`, or the timeout elapses.
+ *
+ * CDP's `Page.navigate` resolves as soon as the request is sent, not
+ * when the page has loaded. Subscribing to lifecycle events would
+ * require a long-lived event channel that the extension-backed
+ * CdpClient cannot currently provide, so this helper polls both
+ * `document.readyState` and `document.location.href` via
+ * {@link evaluateExpression} — which works uniformly across both
+ * Playwright-backed and extension-backed clients.
+ *
+ * The commit-detection step is the interesting part: on same-origin
+ * navigations or cached responses, the browser can return
+ * `readyState === "complete"` from the OLD execution context for a
+ * brief window after `Page.navigate` resolves but before the new
+ * document has been installed. Reading only `readyState` would
+ * accept that stale state and report success against the old URL.
+ * Combining the two observations in a single evaluate and requiring
+ * an observed URL change closes that race.
+ *
+ * Returns `{ finalUrl, timedOut }`. `finalUrl` is the last `href`
+ * observed inside the polling loop (so it reflects the new document
+ * even on commit races) and may differ from `url` if the page
+ * redirected.
+ */
+export async function navigateAndWait(
+  cdp: CdpClient,
+  url: string,
+  opts: { timeoutMs?: number } = {},
+  signal?: AbortSignal,
+): Promise<{ finalUrl: string; timedOut: boolean }> {
+  const timeoutMs = opts.timeoutMs ?? 15_000;
+
+  // Capture the pre-navigation URL so the polling loop can detect
+  // when the new document has committed. If the pre-read fails (rare
+  // — e.g. a fresh about:blank that hasn't initialized a Runtime
+  // context yet), we fall back to readyState-only polling because we
+  // have no baseline to compare against.
+  let urlBeforeNav = "";
+  try {
+    urlBeforeNav = await getCurrentUrl(cdp, signal);
+  } catch {
+    // Non-fatal: urlBeforeNav stays empty and commit detection becomes
+    // a no-op (see `committed` below).
+  }
+
+  // CDP's `Page.navigate` does NOT throw on transport-layer errors
+  // (DNS failure, connection refused, etc.). Instead it resolves with
+  // `{ frameId, errorText? }` and we have to surface the failure
+  // ourselves. Otherwise we silently start polling readyState on the
+  // OLD page (which is "complete") and report success with the stale
+  // URL.
+  const navResp = await cdp.send<{ frameId?: string; errorText?: string }>(
+    "Page.navigate",
+    { url },
+    signal,
+  );
+  if (navResp?.errorText) {
+    throw new CdpError("cdp_error", navResp.errorText, {
+      cdpMethod: "Page.navigate",
+      cdpParams: { url },
+    });
+  }
+
+  // Same-URL reloads (including `about:blank` → `about:blank`) can't
+  // be detected via URL change. Fall back to readyState-only polling
+  // in that case, matching the pre-commit-detection behavior.
+  const sameUrlReload = urlBeforeNav !== "" && url === urlBeforeNav;
+
+  const startedAt = Date.now();
+  // Track exit reason explicitly so the post-loop classification does
+  // not race against `Date.now()` (the final read could otherwise
+  // push us across the timeout boundary and falsely flip `timedOut`
+  // back to true).
+  let completed = false;
+  // Track the last href we successfully observed from inside the
+  // loop. We prefer this to a post-loop `getCurrentUrl` call because
+  // the latter races the very same commit window that motivates the
+  // in-loop commit check.
+  let lastKnownHref = urlBeforeNav;
+
+  while (Date.now() - startedAt < timeoutMs) {
+    if (signal?.aborted) {
+      throw new CdpError("aborted", "Navigation aborted");
+    }
+
+    // Query `readyState` and `location.href` in a single evaluate so
+    // the two observations come from the same execution context and
+    // cannot straddle a commit boundary.
+    try {
+      const snapshot = await evaluateExpression<{
+        readyState: string;
+        href: string;
+      }>(
+        cdp,
+        "({ readyState: document.readyState, href: document.location.href })",
+        {},
+        signal,
+      );
+      if (snapshot && typeof snapshot.href === "string") {
+        lastKnownHref = snapshot.href;
+      }
+      const readyStateOk =
+        snapshot?.readyState === "interactive" ||
+        snapshot?.readyState === "complete";
+      // On cross-URL navigations, require BOTH a ready readyState
+      // AND an observed URL change so we don't accept the OLD
+      // page's "complete" state before the new document has
+      // committed. Same-URL reloads and missing pre-nav URLs fall
+      // back to readyState-only because there's nothing to compare.
+      const committed =
+        sameUrlReload ||
+        urlBeforeNav === "" ||
+        (typeof snapshot?.href === "string" && snapshot.href !== urlBeforeNav);
+      if (readyStateOk && committed) {
+        completed = true;
+        break;
+      }
+    } catch (err) {
+      // `Runtime.evaluate` can fail transiently while the old
+      // execution context is being torn down and the new one has
+      // not yet been created ("Execution context was destroyed" /
+      // "Cannot find context with specified id"). Treat CDP errors
+      // as retry-worthy; the timeout bound below guarantees we
+      // don't loop forever. Abort errors are re-thrown so the
+      // caller's AbortSignal is still honoured promptly.
+      if (err instanceof CdpError && err.code === "aborted") throw err;
+      if (!(err instanceof CdpError)) throw err;
+    }
+
+    await new Promise((r) => setTimeout(r, 100));
+  }
+
+  const timedOut = !completed;
+
+  // Prefer the last href observed inside the loop. If the loop never
+  // produced a successful observation (e.g. all evaluates failed to
+  // transient context errors), fall back to `getCurrentUrl` as a
+  // best-effort read.
+  let finalUrl = lastKnownHref;
+  if (finalUrl === "") {
+    try {
+      finalUrl = await getCurrentUrl(cdp, signal);
+    } catch {
+      // Nothing more to do — surface empty string and let the caller
+      // decide how to render it.
+    }
+  }
+  return { finalUrl, timedOut };
+}
+
+/**
+ * Poll until a selector matches an element in the requested state,
+ * then return its `backendNodeId`. Throws {@link CdpError} on timeout
+ * or abort.
+ *
+ * `state` controls the readiness check:
+ * - `"visible"` (default): the element must be in the DOM AND have a
+ *   non-zero bounding box AND not be `display:none` /
+ *   `visibility:hidden`. This matches Playwright's
+ *   `page.waitForSelector` default and is the right semantics for
+ *   click/hover targets that may be hydrated asynchronously.
+ * - `"attached"`: the element only needs to exist in the DOM. Useful
+ *   for `browser_wait_for` selector mode where the caller just wants
+ *   to know "did this node appear at all" regardless of layout.
+ */
+export async function waitForSelector(
+  cdp: CdpClient,
+  selector: string,
+  timeoutMs: number,
+  signal?: AbortSignal,
+  opts: { state?: "attached" | "visible" } = {},
+): Promise<number> {
+  const state = opts.state ?? "visible";
+  const startedAt = Date.now();
+  const escapedSel = JSON.stringify(selector);
+  const expression =
+    state === "visible"
+      ? `(() => {
+          const el = document.querySelector(${escapedSel});
+          if (!el) return false;
+          const r = el.getBoundingClientRect();
+          const cs = getComputedStyle(el);
+          return r.width > 0 && r.height > 0 && cs.display !== "none" && cs.visibility !== "hidden";
+        })()`
+      : `document.querySelector(${escapedSel}) !== null`;
+  while (Date.now() - startedAt < timeoutMs) {
+    if (signal?.aborted) {
+      throw new CdpError("aborted", "waitForSelector aborted");
+    }
+    const ready = await evaluateExpression<boolean>(
+      cdp,
+      expression,
+      {},
+      signal,
+    );
+    if (ready) {
+      return await querySelectorBackendNodeId(cdp, selector, signal);
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new CdpError("cdp_error", `Timed out waiting for ${selector}`);
+}
+
+/**
+ * Poll `document.body.innerText` for a substring. Throws
+ * {@link CdpError} on timeout or abort.
+ */
+export async function waitForText(
+  cdp: CdpClient,
+  text: string,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  const escaped = JSON.stringify(text);
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (signal?.aborted) {
+      throw new CdpError("aborted", "waitForText aborted");
+    }
+    const found = await evaluateExpression<boolean>(
+      cdp,
+      `(document.body?.innerText ?? "").includes(${escaped})`,
+      {},
+      signal,
+    );
+    if (found) return;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new CdpError("cdp_error", `Timed out waiting for text: ${text}`);
+}