@yuzc-001/grasp 0.6.6

package/src/layer2-perception/hints.js

@@ -0,0 +1,284 @@
+/**
+ * Layer 2 - 感知层：hints.js
+ * 将当前视口内可交互元素转化为极简语义地图（HintMap）
+ */
+
+/**
+ * 在浏览器页面中采集可交互元素，构建 HintMap。
+ * registry 和 counters 由调用方持有，跨调用复用，保证同一元素 ID 稳定。
+ * @param {import('playwright').Page} page
+ * @param {Map<string, string>} registry  fingerprint → id 映射表
+ * @param {{ B: number, I: number, L: number, S: number }} counters  各前缀已用计数
+ * @returns {Promise<Array<{id: string, type: string, label: string, x: number, y: number, meta: Record<string, string> }>>}
+ */
+export async function buildHintMap(page, registry = new Map(), counters = { B: 0, I: 0, L: 0, S: 0 }) {
+  // 将 registry 序列化传入 browser context（Map 不可直接传）
+  const registryEntries = [...registry.entries()];
+
+  const result = await page.evaluate(({ registryEntries, counters }) => {
+    const reg = new Map(registryEntries);
+    const INTERACTIVE_TAGS = new Set(['button', 'a', 'input', 'select', 'textarea']);
+    const INTERACTIVE_ROLES = new Set([
+      'button', 'link', 'textbox', 'searchbox', 'combobox',
+      'checkbox', 'radio', 'menuitem', 'tab', 'option',
+      'slider', 'spinbutton', 'switch',
+    ]);
+
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+
+    function getCandidatePriority(el, tag, role, isContentEditable) {
+      const inputType = (el.getAttribute('type') || '').toLowerCase();
+      if (isContentEditable || role === 'textbox' || role === 'searchbox' || role === 'combobox') return 5;
+      if (tag === 'textarea') return 4;
+      if (tag === 'input') {
+        if (['text', 'search', 'email', 'url', 'password', 'number', 'tel', ''].includes(inputType)) return 4;
+        if (['file', 'hidden'].includes(inputType)) return 1;
+        return 3;
+      }
+      if (tag === 'button' || role === 'button') return 2;
+      if (tag === 'a' || role === 'link') return 1;
+      return 0;
+    }
+
+    function isSelected(el) {
+      const ariaCurrent = (el.getAttribute('aria-current') || '').toLowerCase();
+      const classAttr = String(el.getAttribute('class') || '');
+      const hasStateClass = classAttr
+        .split(/\s+/)
+        .some((token) => /(^|[-_])(selected|current)($|[-_])/i.test(token));
+      return el.getAttribute('aria-selected') === 'true'
+        || el.getAttribute('data-selected') === 'true'
+        || ['page', 'step', 'location', 'date', 'time', 'true'].includes(ariaCurrent)
+        || hasStateClass
+        || el.classList.contains('selected')
+        || el.classList.contains('is-selected')
+        || el.classList.contains('workspace-item--selected');
+    }
+
+    // 1. 遍历 document.body 下所有元素
+    const walker = document.createTreeWalker(
+      document.body,
+      NodeFilter.SHOW_ELEMENT,
+      null,
+    );
+
+    const candidates = [];
+    let node;
+    while ((node = walker.nextNode())) {
+      const el = /** @type {HTMLElement} */ (node);
+      const tag = el.tagName.toLowerCase();
+      const role = (el.getAttribute('role') || '').toLowerCase();
+
+      // 2. 只处理 INTERACTIVE_TAGS 或 INTERACTIVE_ROLES 或 contenteditable
+      const isContentEditable = el.getAttribute('contenteditable') === 'true' ||
+                                el.getAttribute('contenteditable') === '';
+      if (!INTERACTIVE_TAGS.has(tag) && !INTERACTIVE_ROLES.has(role) && !isContentEditable) continue;
+
+      // 3. 过滤不可见元素
+      const rect = el.getBoundingClientRect();
+      if (rect.width === 0 || rect.height === 0) continue;
+      if (rect.bottom < 0 || rect.top > vh || rect.right < 0 || rect.left > vw) continue;
+
+      const style = window.getComputedStyle(el);
+      if (
+        style.visibility === 'hidden' ||
+        style.display === 'none' ||
+        style.opacity === '0'
+      ) continue;
+
+      const cx = Math.round(rect.left + rect.width / 2);
+      const cy = Math.round(rect.top + rect.height / 2);
+
+      candidates.push({
+        el,
+        tag,
+        role,
+        cx,
+        cy,
+        priority: getCandidatePriority(el, tag, role, isContentEditable),
+      });
+    }
+
+    // 4. 排序：y 优先，x 其次
+    candidates.sort((a, b) => {
+      if (a.cy !== b.cy) return a.cy - b.cy;
+      if (a.cx !== b.cx) return a.cx - b.cx;
+      return b.priority - a.priority;
+    });
+
+    // 5. 去重：中心坐标差 < 5px 视为同一交互点，保留更可操作的候选
+    const filtered = [];
+    for (const c of candidates) {
+      const dupIndex = filtered.findIndex((s) => Math.abs(s.cx - c.cx) < 5 && Math.abs(s.cy - c.cy) < 5);
+      if (dupIndex === -1) {
+        filtered.push(c);
+        continue;
+      }
+
+      const previous = filtered[dupIndex];
+      if (c.priority > previous.priority) {
+        filtered[dupIndex] = c;
+      }
+    }
+
+    // 6. 分配 ID 并构建 Hint 列表
+
+    /**
+     * 根据元素信息确定 ID 前缀。
+     * button → B, input/textarea/textbox/searchbox/combobox → I, link → L, 其他 → S
+     */
+    function getPrefix(tag, role, el) {
+      if (tag === 'button' || role === 'button') return 'B';
+      if (
+        tag === 'input' || tag === 'textarea' ||
+        role === 'textbox' || role === 'searchbox' || role === 'combobox' ||
+        el.getAttribute('contenteditable') === 'true' ||
+        el.getAttribute('contenteditable') === ''
+      ) return 'I';
+      if (tag === 'a' || role === 'link') return 'L';
+      return 'S';
+    }
+
+    /**
+     * 从元素上提取最优 label。
+     * 优先级：aria-label > placeholder > title > alt > innerText前40字 > name > id > tagName
+     */
+    function getLabel(el, tag) {
+      const labelledBy = el.getAttribute('aria-labelledby');
+      if (labelledBy) {
+        const text = labelledBy.trim().split(/\s+/)
+          .map(id => document.getElementById(id)?.textContent?.trim() ?? '')
+          .filter(Boolean).join(' ');
+        if (text) return text;
+      }
+
+      const ariaLabel = el.getAttribute('aria-label');
+      if (ariaLabel && ariaLabel.trim()) return ariaLabel.trim();
+
+      const placeholder = el.getAttribute('placeholder');
+      if (placeholder && placeholder.trim()) return placeholder.trim();
+
+      const title = el.getAttribute('title');
+      if (title && title.trim()) return title.trim();
+
+      const alt = el.getAttribute('alt');
+      if (alt && alt.trim()) return alt.trim();
+
+      const text = (el.innerText || '').trim().slice(0, 40);
+      if (text) return text;
+
+      const name = el.getAttribute('name');
+      if (name && name.trim()) return name.trim();
+
+      const id = el.getAttribute('id');
+      if (id && id.trim()) return id.trim();
+
+      return tag;
+    }
+
+    /**
+     * 生成元素指纹：tag | label前8字（空格转下划线）| 位置取整到20px格
+     * 同一元素在多次扫描中指纹相同，用于稳定 ID 复用。
+     */
+    function fingerprint(tag, label, cx, cy) {
+      const gx = Math.round(cx / 20) * 20;
+      const gy = Math.round(cy / 20) * 20;
+      const text = label.slice(0, 8).replace(/\s+/g, '_');
+      return `${tag}|${text}|${gx}|${gy}`;
+    }
+
+    const newEntries = [];  // 本次新分配的 [fp, id] 对，用于更新 Node.js 侧 registry
+    const results = [];
+
+    for (const { el, tag, role, cx, cy } of filtered) {
+      const isContentEditable = el.getAttribute('contenteditable') === 'true' ||
+        el.getAttribute('contenteditable') === '';
+      // 8. 构建 label（先于指纹计算）
+      const label = getLabel(el, tag);
+      const type = isContentEditable && !role ? 'textbox' : (role || tag);
+      const prefix = getPrefix(tag, role, el);
+
+      // 9. 查指纹注册表，命中则复用 ID，未命中则分配新 ID
+      const fp = fingerprint(tag, label, cx, cy);
+      let id = reg.get(fp);
+      if (!id) {
+        counters[prefix] = (counters[prefix] || 0) + 1;
+        id = `${prefix}${counters[prefix]}`;
+        reg.set(fp, id);
+        newEntries.push([fp, id]);
+      }
+
+      // 10. 写入 data-grasp-id
+      el.setAttribute('data-grasp-id', id);
+      const meta = {
+        name: el.getAttribute('name') ?? '',
+        idAttr: el.getAttribute('id') ?? '',
+        ariaLabel: el.getAttribute('aria-label') ?? '',
+        ariaCurrent: el.getAttribute('aria-current') ?? '',
+        placeholder: el.getAttribute('placeholder') ?? '',
+        contenteditable: isContentEditable,
+        selected: isSelected(el),
+        role,
+        tag,
+      };
+      results.push({ id, type, label, x: cx, y: cy, meta });
+    }
+
+    return { hints: results, newEntries, counters };
+  }, { registryEntries, counters: { ...counters } });
+
+  // 将新分配的指纹 → ID 写回 Node.js 侧 registry
+  for (const [fp, id] of result.newEntries) {
+    registry.set(fp, id);
+  }
+  // 同步更新计数器
+  Object.assign(counters, result.counters);
+
+  return result.hints;
+}
+
+const INPUT_LIKE_TYPES = new Set(['input', 'textarea', 'textbox', 'searchbox', 'combobox']);
+
+function isInputLikeHint(hint = {}) {
+  const type = String(hint.type ?? '').toLowerCase();
+  if (INPUT_LIKE_TYPES.has(type)) return true;
+  if (hint.meta?.contenteditable === true || hint.meta?.contenteditable === 'true') return true;
+  return false;
+}
+
+function normalizeHintLabel(hint = {}) {
+  const candidates = [
+    hint.label,
+    hint.meta?.ariaLabel,
+    hint.meta?.placeholder,
+    hint.meta?.name,
+    hint.meta?.idAttr,
+  ];
+  return candidates
+    .map((value) => String(value ?? '').trim().toLowerCase())
+    .find(Boolean) ?? '';
+}
+
+export function rebindHintCandidate(previous, nextHints) {
+  if (!previous) return null;
+  const candidates = nextHints.filter(
+    (hint) => {
+      const sameType = hint.type === previous.type;
+      const sameInputFamily = isInputLikeHint(previous) && isInputLikeHint(hint);
+      if (!sameType && !sameInputFamily) return false;
+      return normalizeHintLabel(hint) === normalizeHintLabel(previous);
+    }
+  );
+  if (candidates.length === 0) return null;
+
+  const distance = (hint) =>
+    Math.abs(hint.x - previous.x) + Math.abs(hint.y - previous.y);
+
+  return candidates.reduce((best, current) => {
+    if (!best) return current;
+    const bestDistance = distance(best);
+    const currentDistance = distance(current);
+    return currentDistance < bestDistance ? current : best;
+  }, null);
+}

package/src/layer3-action/actions.js

@@ -0,0 +1,400 @@
+// Layer 3 - Action Layer
+// Pointer and keyboard interactions use real CDP mouse/keyboard events to
+// minimize anti-bot fingerprints. Targeted nested-container scrolling is the
+// one deliberate exception: it may use DOM scrollBy for precision when wheel
+// routing to a specific overflow container is unreliable.
+
+/**
+ * Find the nearest scrollable ancestor of an element via browser-side evaluation.
+ * Returns a unique CSS selector for the scrollable container, or null if none found.
+ */
+export async function findScrollableAncestor(page, selector) {
+  return page.evaluate((sel) => {
+    const el = document.querySelector(sel);
+    if (!el) return null;
+
+    let current = el;
+    while (current && current !== document.documentElement) {
+      const style = window.getComputedStyle(current);
+      const overflowY = style.overflowY;
+      const overflowX = style.overflowX;
+      const isNativeScrollable = current.tagName === 'TEXTAREA' ||
+        (current.tagName === 'DIV' && current.contentEditable === 'true');
+      const isCSSScrollable =
+        overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay' ||
+        overflowX === 'auto' || overflowX === 'scroll' || overflowX === 'overlay';
+      const hasOverflow = current.scrollHeight > current.clientHeight || current.scrollWidth > current.clientWidth;
+
+      if ((isNativeScrollable || isCSSScrollable) && hasOverflow) {
+        if (current.id) return `#${CSS.escape(current.id)}`;
+        const graspId = current.getAttribute('data-grasp-id');
+        if (graspId) return `[data-grasp-id="${graspId}"]`;
+        const classes = [...current.classList].map((cls) => `.${CSS.escape(cls)}`).join('');
+        if (classes) {
+          const candidateSelector = `${current.tagName.toLowerCase()}${classes}`;
+          const matches = document.querySelectorAll(candidateSelector);
+          if (matches.length === 1 && matches[0] === current) {
+            return candidateSelector;
+          }
+        }
+      }
+
+      current = current.parentElement;
+    }
+
+    return null;
+  }, selector);
+}
+
+function randomInt(min, max) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * 在元素 boundingBox 内生成随机点击坐标（避免总在正中心）。
+ * @param {{ x: number, y: number, width: number, height: number }} box
+ * @returns {{ x: number, y: number }}
+ */
+function randomPointInBox(box) {
+  // 极小元素（宽或高 < 10px）直接取中心，避免 margin 使可用区域退化为零
+  if (box.width < 10 || box.height < 10) {
+    return { x: Math.round(box.x + box.width / 2), y: Math.round(box.y + box.height / 2) };
+  }
+  const margin = 0.2;
+  const x = box.x + box.width * (margin + Math.random() * (1 - 2 * margin));
+  const y = box.y + box.height * (margin + Math.random() * (1 - 2 * margin));
+  return { x: Math.round(x), y: Math.round(y) };
+}
+
+// 记录每个 page 是否已初始化鼠标位置，避免 session 首次点击从 (0,0) 出发
+const _warmedUpPages = new WeakSet();
+
+async function warmupMouseIfNeeded(page) {
+  if (_warmedUpPages.has(page)) return;
+  _warmedUpPages.add(page);
+  const vp = await page.evaluate(() => ({ w: window.innerWidth, h: window.innerHeight }));
+  // 随机初始位置：水平 30%~70%，垂直 30%~70%，模拟真人屏幕中央区域习惯
+  const x = Math.round(vp.w * (0.3 + Math.random() * 0.4));
+  const y = Math.round(vp.h * (0.3 + Math.random() * 0.4));
+  await page.mouse.move(x, y);
+}
+
+/**
+ * Scroll the page or container by a given amount.
+ * Page scrolling uses real CDP wheel events; targeted container scrolling uses
+ * DOM scrollBy to avoid sending wheel input to the wrong overflow region.
+ * @param {import('playwright').Page} page
+ * @param {'up'|'down'|'left'|'right'} direction
+ * @param {number} [amount=600]
+ * @param {{ selector?: string }} [options]
+ */
+export async function scroll(page, direction, amount = 600, options = {}) {
+  const validDirections = ['up', 'down', 'left', 'right'];
+  if (!validDirections.includes(direction)) {
+    throw new Error(`Invalid scroll direction: "${direction}". Expected one of: ${validDirections.join(', ')}.`);
+  }
+  if (amount === 0) return;
+
+  const isVertical = direction === 'up' || direction === 'down';
+  const delta = (direction === 'down' || direction === 'right') ? amount : -amount;
+  const dx = isVertical ? 0 : delta;
+  const dy = isVertical ? delta : 0;
+
+  if (options.selector) {
+    const scrolled = await page.evaluate(({ selector, dx: scrollX, dy: scrollY }) => {
+      const el = document.querySelector(selector);
+      if (!el) return { ok: false, reason: 'not_found' };
+      el.scrollBy(scrollX, scrollY);
+      return { ok: true, tag: el.tagName.toLowerCase() };
+    }, { selector: options.selector, dx, dy });
+
+    if (!scrolled.ok) {
+      throw new Error(`Scroll target not found: "${options.selector}".`);
+    }
+
+    await page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
+    return;
+  }
+
+  const steps = 5;
+  const stepDx = dx / steps;
+  const stepDy = dy / steps;
+
+  for (let i = 0; i < steps; i++) {
+    await page.mouse.wheel(stepDx, stepDy);
+    await new Promise((r) => setTimeout(r, 20 + Math.random() * 40));
+  }
+
+  await page.evaluate(() => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r))));
+}
+
+/**
+ * Locate an element by hint ID.
+ * If the element is not in the viewport, naturally scrolls to bring it into view.
+ * @param {import('playwright').Page} page
+ * @param {string} hintId
+ * @returns {Promise<{ info: { tag: string, label: string }, el: import('playwright').ElementHandle }>}
+ */
+async function locateElement(page, hintId, options = {}) {
+  // 检查元素是否存在以及是否在视口内
+  const defaultEvaluateHint = (id) => page.evaluate((targetId) => {
+    const el = document.querySelector(`[data-grasp-id="${targetId}"]`);
+    if (!el) return null;
+    const rect = el.getBoundingClientRect();
+    const centerX = rect.left + rect.width / 2;
+    const centerY = rect.top + rect.height / 2;
+    const inView = (
+      centerX >= 0 && centerX <= window.innerWidth &&
+      centerY >= 0 && centerY <= window.innerHeight
+    );
+    return {
+      inView,
+      centerY,
+      tag: el.tagName.toLowerCase(),
+      label:
+        el.getAttribute('aria-label') ||
+        el.getAttribute('placeholder') ||
+        el.innerText?.trim() ||
+        '',
+    };
+  }, id);
+
+  const evaluateHint = options.evaluateHint ?? defaultEvaluateHint;
+  const fetchHandle = async (id) => page.$(`[data-grasp-id="${id}"]`);
+  const ensureActionableHandle = async (id, currentInfo) => {
+    let handle = await fetchHandle(id);
+    let box = handle && typeof handle.boundingBox === 'function'
+      ? await handle.boundingBox()
+      : null;
+
+    const actionable = !!(box && box.width > 0 && box.height > 0);
+    if (actionable || typeof options.rebuildHints !== 'function') {
+      return { handle, reboundId: id, reboundInfo: currentInfo };
+    }
+
+    const rebound = await options.rebuildHints(id);
+    if (!rebound?.id || rebound.id === id) {
+      return { handle, reboundId: id, reboundInfo: currentInfo };
+    }
+
+    const reboundInfo = await evaluateHint(rebound.id);
+    const reboundHandle = await fetchHandle(rebound.id);
+    return { handle: reboundHandle, reboundId: rebound.id, reboundInfo };
+  };
+
+  let viewportCheck = await evaluateHint(hintId);
+  if (viewportCheck === null && typeof options.rebuildHints === 'function') {
+    const rebound = await options.rebuildHints(hintId);
+    if (rebound?.id) {
+      hintId = rebound.id;
+    }
+    viewportCheck = await evaluateHint(hintId);
+  }
+
+  if (viewportCheck === null) {
+    throw new Error(`No element with hint ID "${hintId}". Call get_hint_map first.`);
+  }
+
+  // 如果不在视口内，用真实滚动将其带入视野
+  if (!viewportCheck.inView) {
+    const vh = await page.evaluate(() => window.innerHeight);
+    const scrollNeeded = viewportCheck.centerY - vh / 2;
+    const direction = scrollNeeded > 0 ? 'down' : 'up';
+    const amount = Math.abs(scrollNeeded);
+    await scroll(page, direction, amount);
+    // 等待滚动动画完成
+    await new Promise((r) => setTimeout(r, 300));
+  }
+
+  const actionable = await ensureActionableHandle(hintId, viewportCheck);
+  hintId = actionable.reboundId;
+  viewportCheck = actionable.reboundInfo ?? viewportCheck;
+  const el = actionable.handle;
+  if (el === null) {
+    throw new Error(`Element "${hintId}" disappeared after scrolling.`);
+  }
+
+  return {
+    info: { tag: viewportCheck.tag, label: viewportCheck.label },
+    el,
+  };
+}
+
+/**
+ * Click an element identified by its hint ID.
+ * Moves the mouse naturally to the element before clicking.
+ * @param {import('playwright').Page} page
+ * @param {string} hintId
+ * @returns {Promise<{ tag: string, label: string }>}
+ */
+export async function clickByHintId(page, hintId, options = {}) {
+  const { info, el } = await locateElement(page, hintId, options);
+  const clickCount = Math.max(1, Number(options.clickCount ?? 1));
+
+  // 获取元素真实坐标
+  const box = await el.boundingBox();
+  if (!box) throw new Error(`Element "${hintId}" (<${info.tag}> "${info.label}") has no bounding box (may be hidden).`);
+
+  // 在元素内随机取一个点
+  const target = randomPointInBox(box);
+
+  // 先把鼠标从当前位置移动过来（分 15 步，模拟自然移动轨迹）
+  await warmupMouseIfNeeded(page);
+  await page.mouse.move(target.x, target.y, { steps: 15 });
+
+  if (clickCount > 1) {
+    await page.mouse.click(target.x, target.y, { clickCount });
+  } else {
+    // 按下 + 随机持续时间 + 抬起，模拟人类按键
+    await page.mouse.down();
+    await new Promise((r) => setTimeout(r, randomInt(40, 120)));
+    await page.mouse.up();
+  }
+
+  // 等待页面响应（networkidle 或超时）
+  await page.waitForLoadState('networkidle', { timeout: 5000 }).catch(() => {});
+
+  return info;
+}
+
+/**
+ * Type text into an element identified by its hint ID.
+ * @param {import('playwright').Page} page
+ * @param {string} hintId
+ * @param {string} text
+ * @param {boolean} [pressEnter=false]
+ */
+export async function typeByHintId(page, hintId, text, pressEnter = false, options = {}) {
+  const { el } = await locateElement(page, hintId, options);
+
+  // 三连击全选：优先用真实鼠标坐标事件，兼容 React 受控输入
+  const box = await el.boundingBox();
+  if (box) {
+    const target = randomPointInBox(box);
+    await warmupMouseIfNeeded(page);
+    await page.mouse.move(target.x, target.y, { steps: 15 });
+    await page.mouse.click(target.x, target.y, { clickCount: 3 });
+  } else {
+    // 极少数情况元素无坐标，回退到 Playwright 高层 API
+    await el.click({ clickCount: 3 });
+  }
+
+  // 清除已选中文本
+  await page.keyboard.press('Backspace');
+
+  // Step 4: type character by character with random human-like delay
+  await el.type(text, { delay: randomInt(30, 80) });
+
+  // Step 5: optionally press Enter
+  if (pressEnter) {
+    await page.keyboard.press('Enter');
+  }
+}
+
+/**
+ * Watch a DOM element for a specific condition using MutationObserver.
+ * @param {import('playwright').Page} page
+ * @param {string} selector - CSS selector to watch
+ * @param {'appears'|'disappears'|'changes'} [condition='appears']
+ * @param {number} [timeout=30000]
+ * @returns {Promise<{ met?: true, text?: string, timeout?: true }>}
+ */
+export async function watchElement(page, selector, condition = 'appears', timeout = 30000) {
+  return page.evaluate(
+    ({ selector: sel, condition: cond, timeout: ms }) => {
+      return new Promise((resolve) => {
+        let settled = false;
+        let observer;
+        let timer;
+        let initialText;
+
+        function done(result) {
+          if (settled) return;
+          settled = true;
+          observer?.disconnect();
+          clearTimeout(timer);
+          resolve(result);
+        }
+
+        function check() {
+          const el = document.querySelector(sel);
+          if (cond === 'appears') {
+            if (el) {
+              done({ met: true, text: el.innerText?.trim() });
+              return true;
+            }
+          } else if (cond === 'disappears') {
+            if (!el) {
+              done({ met: true });
+              return true;
+            }
+          } else if (cond === 'changes') {
+            if (el) {
+              initialText = el.innerText?.trim();
+            }
+          }
+          return false;
+        }
+
+        const immediatelyMet = check();
+        if (immediatelyMet) return;
+
+        timer = setTimeout(() => {
+          done({ timeout: true });
+        }, ms);
+
+        observer = new MutationObserver(() => {
+          const el = document.querySelector(sel);
+          if (cond === 'appears') {
+            if (el) {
+              done({ met: true, text: el.innerText?.trim() });
+            }
+          } else if (cond === 'disappears') {
+            if (!el) {
+              done({ met: true });
+            }
+          } else if (cond === 'changes') {
+            if (el) {
+              const current = el.innerText?.trim();
+              if (current !== initialText) {
+                done({ met: true, text: current });
+              }
+            }
+          }
+        });
+
+        const target = document.querySelector(sel);
+        if (target) {
+          observer.observe(target, { childList: true, subtree: true, characterData: true });
+        } else {
+          observer.observe(document.body, { childList: true, subtree: true });
+        }
+      });
+    },
+    { selector, condition, timeout }
+  );
+}
+
+/**
+ * Press a keyboard key or shortcut (e.g. 'Enter', 'Escape', 'Control+Enter').
+ * @param {import('playwright').Page} page
+ * @param {string} key
+ */
+export async function pressKey(page, key) {
+  await page.keyboard.press(key);
+}
+
+/**
+ * Hover over an element by its Hint Map ID to trigger dropdowns or tooltips.
+ * @param {import('playwright').Page} page
+ * @param {string} hintId
+ */
+export async function hoverByHintId(page, hintId, options = {}) {
+  const { info, el } = await locateElement(page, hintId, options);
+  await el.hover();
+  // Allow hover-triggered animations/menus to settle
+  await new Promise((r) => setTimeout(r, 200));
+  return info;
+}
+
+export { locateElement };