btcp-browser-agent 0.1.0

package/packages/core/src/actions.ts

@@ -0,0 +1,1210 @@
+/**
+ * @btcp/core - DOM Actions
+ *
+ * Element interaction handlers using native browser APIs.
+ */
+
+import type {
+  Command,
+  Response,
+  RefMap,
+  BoundingBox,
+  SnapshotData,
+  Modifier,
+  ValidateElementResponse,
+  ValidateRefsResponse,
+} from './types.js';
+import { createSnapshot } from './snapshot.js';
+import {
+  DetailedError,
+  createElementNotFoundError,
+  createElementNotCompatibleError,
+  createTimeoutError,
+  createInvalidParametersError,
+} from './errors.js';
+
+/**
+ * DOM Actions executor
+ */
+export class DOMActions {
+  private document: Document;
+  private window: Window;
+  private refMap: RefMap;
+  private lastSnapshotData: SnapshotData | null = null;
+  private overlayContainer: HTMLElement | null = null;
+  private scrollListener: (() => void) | null = null;
+  private rafId: number | null = null;
+
+  constructor(doc: Document, win: Window, refMap: RefMap) {
+    this.document = doc;
+    this.window = win;
+    this.refMap = refMap;
+  }
+
+  /**
+   * Execute a command and return a response
+   */
+  async execute(command: Command): Promise<Response> {
+    try {
+      const data = await this.dispatch(command);
+      return { id: command.id, success: true, data };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+
+      // Include structured error data if available
+      if (error instanceof DetailedError) {
+        return {
+          id: command.id,
+          success: false,
+          error: message,
+          errorCode: error.code,
+          errorContext: error.context,
+          suggestions: error.suggestions,
+        };
+      }
+
+      return { id: command.id, success: false, error: message };
+    }
+  }
+
+  private async dispatch(command: Command): Promise<unknown> {
+    switch (command.action) {
+      case 'click':
+        return this.click(command.selector, {
+          button: command.button,
+          clickCount: command.clickCount,
+          modifiers: command.modifiers,
+        });
+
+      case 'dblclick':
+        return this.dblclick(command.selector);
+
+      case 'type':
+        return this.type(command.selector, command.text, {
+          delay: command.delay,
+          clear: command.clear,
+        });
+
+      case 'fill':
+        return this.fill(command.selector, command.value);
+
+      case 'clear':
+        return this.clear(command.selector);
+
+      case 'check':
+        return this.check(command.selector);
+
+      case 'uncheck':
+        return this.uncheck(command.selector);
+
+      case 'select':
+        return this.select(command.selector, command.values);
+
+      case 'focus':
+        return this.focus(command.selector);
+
+      case 'blur':
+        return this.blur(command.selector);
+
+      case 'hover':
+        return this.hover(command.selector);
+
+      case 'scroll':
+        return this.scroll(command.selector, {
+          x: command.x,
+          y: command.y,
+          direction: command.direction,
+          amount: command.amount,
+        });
+
+      case 'scrollIntoView':
+        return this.scrollIntoView(command.selector, command.block);
+
+      case 'snapshot':
+        return this.snapshot({
+          selector: command.selector,
+          maxDepth: command.maxDepth,
+          includeHidden: command.includeHidden,
+          interactive: command.interactive,
+          compact: command.compact,
+          all: command.all,
+          format: command.format,
+          grep: command.grep,
+        });
+
+      case 'querySelector':
+        return this.querySelector(command.selector);
+
+      case 'querySelectorAll':
+        return this.querySelectorAll(command.selector);
+
+      case 'getText':
+        return this.getText(command.selector);
+
+      case 'getAttribute':
+        return this.getAttribute(command.selector, command.attribute);
+
+      case 'getProperty':
+        return this.getProperty(command.selector, command.property);
+
+      case 'getBoundingBox':
+        return this.getBoundingBox(command.selector);
+
+      case 'isVisible':
+        return this.isVisible(command.selector);
+
+      case 'isEnabled':
+        return this.isEnabled(command.selector);
+
+      case 'isChecked':
+        return this.isChecked(command.selector);
+
+      case 'press':
+        return this.press(command.key, command.selector, command.modifiers);
+
+      case 'keyDown':
+        return this.keyDown(command.key);
+
+      case 'keyUp':
+        return this.keyUp(command.key);
+
+      case 'wait':
+        return this.wait(command.selector, {
+          state: command.state,
+          timeout: command.timeout,
+        });
+
+      case 'evaluate':
+        return this.evaluate(command.script, command.args);
+
+      case 'validateElement':
+        return this.validateElement(command.selector, {
+          expectedType: command.expectedType,
+          capabilities: command.capabilities,
+        });
+
+      case 'validateRefs':
+        return this.validateRefs(command.refs);
+
+      case 'highlight':
+        return this.highlight();
+
+      case 'clearHighlight':
+        return this.clearHighlight();
+
+      default:
+        throw new Error(`Unknown action: ${(command as Command).action}`);
+    }
+  }
+
+  // --- Element Resolution ---
+
+  private getElement(selector: string): Element {
+    const element = this.queryElement(selector);
+    if (!element) {
+      const isRef = selector.startsWith('@ref:');
+      const similarSelectors = isRef ? [] : this.findSimilarSelectors(selector);
+      const nearbyElements = this.getNearbyInteractiveElements();
+
+      throw createElementNotFoundError(selector, {
+        similarSelectors,
+        nearbyElements: nearbyElements.slice(0, 5),
+        isRef,
+      });
+    }
+    return element;
+  }
+
+  /**
+   * Find selectors similar to the given selector
+   */
+  private findSimilarSelectors(selector: string): Array<{ selector: string; role: string; name: string }> {
+    const results: Array<{ selector: string; role: string; name: string }> = [];
+
+    try {
+      // Try to extract ID or class from selector
+      const idMatch = selector.match(/#([a-zA-Z0-9_-]+)/);
+      const classMatch = selector.match(/\.([a-zA-Z0-9_-]+)/);
+
+      if (idMatch) {
+        // Look for similar IDs
+        const targetId = idMatch[1].toLowerCase();
+        const allElements = this.document.querySelectorAll('[id]');
+        allElements.forEach(el => {
+          const elId = el.id.toLowerCase();
+          if (elId !== targetId && (elId.includes(targetId) || targetId.includes(elId))) {
+            const role = el.getAttribute('role') || el.tagName.toLowerCase();
+            const name = el.textContent?.trim().substring(0, 30) || el.getAttribute('aria-label') || '';
+            results.push({
+              selector: `#${el.id}`,
+              role,
+              name,
+            });
+          }
+        });
+      }
+
+      if (classMatch && results.length < 3) {
+        // Look for similar classes
+        const targetClass = classMatch[1].toLowerCase();
+        const allElements = this.document.querySelectorAll('[class]');
+        allElements.forEach(el => {
+          const classes = Array.from(el.classList).map(c => c.toLowerCase());
+          const similarClass = classes.find(c => c !== targetClass && (c.includes(targetClass) || targetClass.includes(c)));
+          if (similarClass) {
+            const role = el.getAttribute('role') || el.tagName.toLowerCase();
+            const name = el.textContent?.trim().substring(0, 30) || el.getAttribute('aria-label') || '';
+            results.push({
+              selector: `.${similarClass}`,
+              role,
+              name,
+            });
+          }
+        });
+      }
+    } catch (e) {
+      // Ignore errors in similarity search
+    }
+
+    return results.slice(0, 3);
+  }
+
+  /**
+   * Get nearby interactive elements
+   */
+  private getNearbyInteractiveElements(): Array<{ ref: string; role: string; name: string }> {
+    const results: Array<{ ref: string; role: string; name: string }> = [];
+
+    try {
+      const interactiveSelectors = [
+        'button',
+        'a[href]',
+        'input',
+        'textarea',
+        'select',
+        '[role="button"]',
+        '[role="link"]',
+        '[tabindex]'
+      ];
+
+      const elements = this.document.querySelectorAll(interactiveSelectors.join(','));
+
+      elements.forEach(el => {
+        if (el instanceof HTMLElement) {
+          const style = this.window.getComputedStyle(el);
+          const isVisible = style.display !== 'none' && style.visibility !== 'hidden';
+
+          if (isVisible) {
+            const ref = this.refMap.generateRef(el);
+            const role = el.getAttribute('role') || el.tagName.toLowerCase();
+            const name = el.textContent?.trim().substring(0, 30) ||
+                        el.getAttribute('aria-label') ||
+                        (el as HTMLInputElement).value?.substring(0, 30) ||
+                        (el as HTMLInputElement).placeholder ||
+                        '';
+
+            results.push({ ref, role, name });
+          }
+        }
+      });
+    } catch (e) {
+      // Ignore errors in nearby element search
+    }
+
+    return results.slice(0, 10);
+  }
+
+  /**
+   * Get available actions for an element based on its type
+   */
+  private getAvailableActionsForElement(element: Element): string[] {
+    const actions: string[] = [];
+
+    // All elements can be queried and inspected
+    actions.push('querySelector', 'getText', 'getAttribute', 'getProperty', 'getBoundingBox', 'isVisible');
+
+    // Clickable elements
+    if (
+      element instanceof HTMLButtonElement ||
+      element instanceof HTMLAnchorElement ||
+      element.getAttribute('role') === 'button' ||
+      element.getAttribute('role') === 'link' ||
+      element.hasAttribute('onclick')
+    ) {
+      actions.push('click', 'dblclick', 'hover');
+    }
+
+    // Input elements
+    if (element instanceof HTMLInputElement) {
+      actions.push('fill', 'clear', 'focus', 'blur', 'isEnabled');
+
+      if (element.type === 'checkbox' || element.type === 'radio') {
+        actions.push('check', 'uncheck', 'isChecked');
+      } else {
+        actions.push('type');
+      }
+    }
+
+    // Textarea elements
+    if (element instanceof HTMLTextAreaElement) {
+      actions.push('type', 'fill', 'clear', 'focus', 'blur');
+    }
+
+    // Select elements
+    if (element instanceof HTMLSelectElement) {
+      actions.push('select', 'focus', 'blur');
+    }
+
+    // Focusable elements
+    if (element instanceof HTMLElement) {
+      actions.push('focus', 'blur', 'scroll', 'scrollIntoView', 'press');
+    }
+
+    return actions;
+  }
+
+  private queryElement(selector: string): Element | null {
+    // Check if it's a ref
+    if (selector.startsWith('@ref:')) {
+      return this.refMap.get(selector);
+    }
+
+    // CSS selector
+    return this.document.querySelector(selector);
+  }
+
+  private queryElements(selector: string): Element[] {
+    if (selector.startsWith('@ref:')) {
+      const el = this.refMap.get(selector);
+      return el ? [el] : [];
+    }
+    return Array.from(this.document.querySelectorAll(selector));
+  }
+
+  // --- Actions ---
+
+  private async click(
+    selector: string,
+    options: { button?: 'left' | 'right' | 'middle'; clickCount?: number; modifiers?: Modifier[] } = {}
+  ): Promise<{ clicked: true }> {
+    const element = this.getElement(selector);
+    const { button = 'left', clickCount = 1, modifiers = [] } = options;
+
+    if (element instanceof HTMLElement) {
+      element.focus();
+    }
+
+    const buttonCode = button === 'right' ? 2 : button === 'middle' ? 1 : 0;
+    const eventInit: MouseEventInit = {
+      bubbles: true,
+      cancelable: true,
+      button: buttonCode,
+      altKey: modifiers.includes('Alt'),
+      ctrlKey: modifiers.includes('Control'),
+      metaKey: modifiers.includes('Meta'),
+      shiftKey: modifiers.includes('Shift'),
+    };
+
+    for (let i = 0; i < clickCount; i++) {
+      element.dispatchEvent(new MouseEvent('mousedown', eventInit));
+      element.dispatchEvent(new MouseEvent('mouseup', eventInit));
+      element.dispatchEvent(new MouseEvent('click', eventInit));
+    }
+
+    return { clicked: true };
+  }
+
+  private async dblclick(selector: string): Promise<{ clicked: true }> {
+    const element = this.getElement(selector);
+    element.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }));
+    return { clicked: true };
+  }
+
+  private async type(
+    selector: string,
+    text: string,
+    options: { delay?: number; clear?: boolean } = {}
+  ): Promise<{ typed: true }> {
+    const element = this.getElement(selector);
+
+    if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) {
+      const actualType = element.tagName.toLowerCase();
+      const availableActions = this.getAvailableActionsForElement(element);
+
+      throw createElementNotCompatibleError(
+        selector,
+        'type',
+        actualType,
+        ['input', 'textarea'],
+        availableActions
+      );
+    }
+
+    element.focus();
+
+    if (options.clear) {
+      element.value = '';
+      element.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+
+    for (const char of text) {
+      element.dispatchEvent(new KeyboardEvent('keydown', { key: char, bubbles: true }));
+      element.dispatchEvent(new KeyboardEvent('keypress', { key: char, bubbles: true }));
+      element.value += char;
+      element.dispatchEvent(new Event('input', { bubbles: true }));
+      element.dispatchEvent(new KeyboardEvent('keyup', { key: char, bubbles: true }));
+
+      if (options.delay) {
+        await this.sleep(options.delay);
+      }
+    }
+
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+    return { typed: true };
+  }
+
+  private async fill(selector: string, value: string): Promise<{ filled: true }> {
+    const element = this.getElement(selector);
+
+    if (!(element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement)) {
+      const actualType = element.tagName.toLowerCase();
+      const availableActions = this.getAvailableActionsForElement(element);
+
+      throw createElementNotCompatibleError(
+        selector,
+        'fill',
+        actualType,
+        ['input', 'textarea'],
+        availableActions
+      );
+    }
+
+    element.focus();
+    element.value = value;
+    element.dispatchEvent(new Event('input', { bubbles: true }));
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+
+    return { filled: true };
+  }
+
+  private async clear(selector: string): Promise<{ cleared: true }> {
+    const element = this.getElement(selector);
+
+    if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+      element.value = '';
+      element.dispatchEvent(new Event('input', { bubbles: true }));
+      element.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+
+    return { cleared: true };
+  }
+
+  private async check(selector: string): Promise<{ checked: true }> {
+    const element = this.getElement(selector);
+
+    if (!(element instanceof HTMLInputElement)) {
+      const actualType = element.tagName.toLowerCase();
+      const availableActions = this.getAvailableActionsForElement(element);
+
+      throw createElementNotCompatibleError(
+        selector,
+        'check',
+        actualType,
+        ['input[type=checkbox]', 'input[type=radio]'],
+        availableActions
+      );
+    }
+
+    if (!element.checked) {
+      element.click();
+    }
+
+    return { checked: true };
+  }
+
+  private async uncheck(selector: string): Promise<{ unchecked: true }> {
+    const element = this.getElement(selector);
+
+    if (!(element instanceof HTMLInputElement)) {
+      const actualType = element.tagName.toLowerCase();
+      const availableActions = this.getAvailableActionsForElement(element);
+
+      throw createElementNotCompatibleError(
+        selector,
+        'uncheck',
+        actualType,
+        ['input[type=checkbox]'],
+        availableActions
+      );
+    }
+
+    if (element.checked) {
+      element.click();
+    }
+
+    return { unchecked: true };
+  }
+
+  private async select(selector: string, values: string | string[]): Promise<{ selected: string[] }> {
+    const element = this.getElement(selector);
+
+    if (!(element instanceof HTMLSelectElement)) {
+      const actualType = element.tagName.toLowerCase();
+      const availableActions = this.getAvailableActionsForElement(element);
+
+      throw createElementNotCompatibleError(
+        selector,
+        'select',
+        actualType,
+        ['select'],
+        availableActions
+      );
+    }
+
+    const valueArray = Array.isArray(values) ? values : [values];
+
+    for (const option of element.options) {
+      option.selected = valueArray.includes(option.value);
+    }
+
+    element.dispatchEvent(new Event('change', { bubbles: true }));
+
+    return { selected: valueArray };
+  }
+
+  private async focus(selector: string): Promise<{ focused: true }> {
+    const element = this.getElement(selector);
+
+    if (element instanceof HTMLElement) {
+      element.focus();
+    }
+
+    return { focused: true };
+  }
+
+  private async blur(selector: string): Promise<{ blurred: true }> {
+    const element = this.getElement(selector);
+
+    if (element instanceof HTMLElement) {
+      element.blur();
+    }
+
+    return { blurred: true };
+  }
+
+  private async hover(selector: string): Promise<{ hovered: true }> {
+    const element = this.getElement(selector);
+
+    element.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+    element.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+
+    return { hovered: true };
+  }
+
+  private async scroll(
+    selector: string | undefined,
+    options: { x?: number; y?: number; direction?: string; amount?: number }
+  ): Promise<{ scrolled: true }> {
+    // Validate parameter combinations
+    const hasXY = options.x !== undefined || options.y !== undefined;
+    const hasDirection = options.direction !== undefined;
+
+    if (hasXY && hasDirection) {
+      throw createInvalidParametersError(
+        'Scroll command has conflicting parameters',
+        ['x/y', 'direction'],
+        'Use either { x, y } for absolute scrolling OR { direction, amount } for relative scrolling, not both'
+      );
+    }
+
+    let deltaX = options.x ?? 0;
+    let deltaY = options.y ?? 0;
+
+    if (options.direction) {
+      const amount = options.amount ?? 100;
+      switch (options.direction) {
+        case 'up': deltaY = -amount; break;
+        case 'down': deltaY = amount; break;
+        case 'left': deltaX = -amount; break;
+        case 'right': deltaX = amount; break;
+      }
+    }
+
+    if (selector) {
+      const element = this.getElement(selector);
+      element.scrollBy(deltaX, deltaY);
+    } else {
+      this.window.scrollBy(deltaX, deltaY);
+    }
+
+    return { scrolled: true };
+  }
+
+  private async scrollIntoView(
+    selector: string,
+    block: 'start' | 'center' | 'end' | 'nearest' = 'center'
+  ): Promise<{ scrolled: true }> {
+    const element = this.getElement(selector);
+    element.scrollIntoView({ behavior: 'smooth', block });
+    return { scrolled: true };
+  }
+
+  private async snapshot(options: {
+    selector?: string;
+    maxDepth?: number;
+    includeHidden?: boolean;
+    interactive?: boolean;
+    compact?: boolean;
+    all?: boolean;
+    format?: 'tree' | 'html';
+    grep?: string | { pattern: string; ignoreCase?: boolean; invert?: boolean; fixedStrings?: boolean };
+  }): Promise<string> {
+    const root = options.selector
+      ? this.getElement(options.selector)
+      : this.document.body;
+
+    const snapshotData = createSnapshot(this.document, this.refMap, {
+      root,
+      maxDepth: options.maxDepth,
+      includeHidden: options.includeHidden,
+      interactive: options.interactive,
+      compact: options.compact,
+      all: options.all,
+      format: options.format,
+      grep: options.grep,
+    });
+
+    // Store snapshot data for highlight command (preserve refs internally)
+    this.lastSnapshotData = snapshotData;
+
+    // Return only the tree string
+    return snapshotData.tree;
+  }
+
+  private async querySelector(selector: string): Promise<{ found: boolean; ref?: string }> {
+    const element = this.queryElement(selector);
+    if (!element) {
+      return { found: false };
+    }
+
+    const ref = this.refMap.generateRef(element);
+    return { found: true, ref };
+  }
+
+  private async querySelectorAll(selector: string): Promise<{ count: number; refs: string[] }> {
+    const elements = this.queryElements(selector);
+    const refs = elements.map((el) => this.refMap.generateRef(el));
+    return { count: elements.length, refs };
+  }
+
+  private async getText(selector: string): Promise<{ text: string | null }> {
+    const element = this.getElement(selector);
+    return { text: element.textContent };
+  }
+
+  private async getAttribute(selector: string, attribute: string): Promise<{ value: string | null }> {
+    const element = this.getElement(selector);
+    return { value: element.getAttribute(attribute) };
+  }
+
+  private async getProperty(selector: string, property: string): Promise<{ value: unknown }> {
+    const element = this.getElement(selector);
+    return { value: (element as unknown as Record<string, unknown>)[property] };
+  }
+
+  private async getBoundingBox(selector: string): Promise<{ box: BoundingBox }> {
+    const element = this.getElement(selector);
+    const rect = element.getBoundingClientRect();
+    return {
+      box: {
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height,
+      },
+    };
+  }
+
+  private async isVisible(selector: string): Promise<{ visible: boolean }> {
+    const element = this.queryElement(selector);
+    if (!element || !(element instanceof HTMLElement)) {
+      return { visible: false };
+    }
+
+    const style = this.window.getComputedStyle(element);
+    const visible =
+      style.display !== 'none' &&
+      style.visibility !== 'hidden' &&
+      style.opacity !== '0';
+
+    return { visible };
+  }
+
+  private async isEnabled(selector: string): Promise<{ enabled: boolean }> {
+    const element = this.getElement(selector);
+    const enabled = !(element as HTMLInputElement).disabled;
+    return { enabled };
+  }
+
+  private async isChecked(selector: string): Promise<{ checked: boolean }> {
+    const element = this.getElement(selector);
+    const checked = (element as HTMLInputElement).checked ?? false;
+    return { checked };
+  }
+
+  private async press(
+    key: string,
+    selector?: string,
+    modifiers: Modifier[] = []
+  ): Promise<{ pressed: true }> {
+    const target = selector
+      ? this.getElement(selector)
+      : this.document.activeElement || this.document.body;
+
+    const eventInit: KeyboardEventInit = {
+      key,
+      code: key,
+      bubbles: true,
+      cancelable: true,
+      altKey: modifiers.includes('Alt'),
+      ctrlKey: modifiers.includes('Control'),
+      metaKey: modifiers.includes('Meta'),
+      shiftKey: modifiers.includes('Shift'),
+    };
+
+    target.dispatchEvent(new KeyboardEvent('keydown', eventInit));
+    target.dispatchEvent(new KeyboardEvent('keypress', eventInit));
+    target.dispatchEvent(new KeyboardEvent('keyup', eventInit));
+
+    return { pressed: true };
+  }
+
+  private async keyDown(key: string): Promise<{ down: true }> {
+    const target = this.document.activeElement || this.document.body;
+    target.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
+    return { down: true };
+  }
+
+  private async keyUp(key: string): Promise<{ up: true }> {
+    const target = this.document.activeElement || this.document.body;
+    target.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
+    return { up: true };
+  }
+
+  private async wait(
+    selector?: string,
+    options: { state?: string; timeout?: number } = {}
+  ): Promise<{ waited: true }> {
+    const { state = 'visible', timeout = 5000 } = options;
+
+    if (!selector) {
+      await this.sleep(timeout);
+      return { waited: true };
+    }
+
+    const startTime = Date.now();
+    let lastState: { attached: boolean; visible: boolean; enabled: boolean } | undefined;
+
+    while (Date.now() - startTime < timeout) {
+      const element = this.queryElement(selector);
+
+      // Track element state for error reporting
+      if (element instanceof HTMLElement) {
+        const style = this.window.getComputedStyle(element);
+        lastState = {
+          attached: true,
+          visible: style.display !== 'none' && style.visibility !== 'hidden',
+          enabled: !(element as HTMLInputElement).disabled,
+        };
+      } else if (element) {
+        lastState = {
+          attached: true,
+          visible: false,
+          enabled: true,
+        };
+      }
+
+      let conditionMet = false;
+      switch (state) {
+        case 'attached':
+          conditionMet = element !== null;
+          break;
+        case 'detached':
+          conditionMet = element === null;
+          break;
+        case 'visible':
+          if (element instanceof HTMLElement) {
+            const style = this.window.getComputedStyle(element);
+            conditionMet =
+              style.display !== 'none' &&
+              style.visibility !== 'hidden';
+          }
+          break;
+        case 'hidden':
+          conditionMet =
+            !element ||
+            (element instanceof HTMLElement &&
+              this.window.getComputedStyle(element).display === 'none');
+          break;
+        case 'enabled':
+          conditionMet = element !== null && !(element as HTMLInputElement).disabled;
+          break;
+      }
+
+      if (conditionMet) {
+        return { waited: true };
+      }
+
+      await this.sleep(100);
+    }
+
+    // Provide detailed timeout error with current state
+    throw createTimeoutError(selector, state, lastState);
+  }
+
+  private async evaluate(script: string, args?: unknown[]): Promise<{ result: unknown }> {
+    const fn = new Function(...(args?.map((_, i) => `arg${i}`) || []), `return (${script})`);
+    const result = fn.call(this.window, ...(args || []));
+    return { result };
+  }
+
+  /**
+   * Validate element capabilities before attempting an action
+   */
+  private async validateElement(
+    selector: string,
+    options: {
+      expectedType?: 'input' | 'textarea' | 'button' | 'link' | 'select';
+      capabilities?: Array<'clickable' | 'editable' | 'checkable' | 'hoverable'>;
+    } = {}
+  ): Promise<ValidateElementResponse> {
+    const element = this.getElement(selector);
+    const actualRole = element.getAttribute('role') || element.tagName.toLowerCase();
+    const actualType = element instanceof HTMLInputElement ? element.type : undefined;
+
+    // Get element capabilities
+    const capabilities = this.getAvailableActionsForElement(element);
+
+    // Get element state
+    const style = element instanceof HTMLElement ? this.window.getComputedStyle(element) : null;
+    const state = {
+      attached: true,
+      visible: style ? style.display !== 'none' && style.visibility !== 'hidden' : false,
+      enabled: !(element as HTMLInputElement).disabled,
+    };
+
+    // Check type compatibility
+    let compatible = true;
+    let suggestion: string | undefined;
+
+    if (options.expectedType) {
+      const typeMatch =
+        options.expectedType === actualRole ||
+        (options.expectedType === 'input' && element instanceof HTMLInputElement) ||
+        (options.expectedType === 'textarea' && element instanceof HTMLTextAreaElement) ||
+        (options.expectedType === 'button' && element instanceof HTMLButtonElement) ||
+        (options.expectedType === 'link' && element instanceof HTMLAnchorElement) ||
+        (options.expectedType === 'select' && element instanceof HTMLSelectElement);
+
+      if (!typeMatch) {
+        compatible = false;
+        suggestion = `Element is ${actualRole}, not ${options.expectedType}. Available actions: ${capabilities.slice(0, 5).join(', ')}`;
+      }
+    }
+
+    // Check capability requirements
+    if (options.capabilities && compatible) {
+      const capabilityMap: Record<string, boolean> = {
+        clickable:
+          element instanceof HTMLButtonElement ||
+          element instanceof HTMLAnchorElement ||
+          element.getAttribute('role') === 'button' ||
+          element.hasAttribute('onclick'),
+        editable:
+          element instanceof HTMLInputElement ||
+          element instanceof HTMLTextAreaElement,
+        checkable:
+          element instanceof HTMLInputElement &&
+          (element.type === 'checkbox' || element.type === 'radio'),
+        hoverable: element instanceof HTMLElement,
+      };
+
+      for (const cap of options.capabilities) {
+        if (!capabilityMap[cap]) {
+          compatible = false;
+          suggestion = `Element does not support capability: ${cap}. Available actions: ${capabilities.slice(0, 5).join(', ')}`;
+          break;
+        }
+      }
+    }
+
+    return {
+      compatible,
+      actualRole,
+      actualType,
+      capabilities,
+      state,
+      suggestion,
+    };
+  }
+
+  /**
+   * Validate that refs are still valid
+   */
+  private async validateRefs(refs: string[]): Promise<ValidateRefsResponse> {
+    const valid: string[] = [];
+    const invalid: string[] = [];
+    const reasons: Record<string, string> = {};
+
+    for (const ref of refs) {
+      const element = this.refMap.get(ref);
+
+      if (element) {
+        // Check if element is still in the DOM
+        if (this.document.contains(element)) {
+          valid.push(ref);
+        } else {
+          invalid.push(ref);
+          reasons[ref] = 'Element has been removed from the DOM';
+        }
+      } else {
+        invalid.push(ref);
+        reasons[ref] = 'Ref not found. Refs are cleared on each snapshot() call.';
+      }
+    }
+
+    return {
+      valid,
+      invalid,
+      reasons,
+    };
+  }
+
+  /**
+   * Display visual overlay labels for interactive elements
+   */
+  private async highlight(): Promise<{ highlighted: number }> {
+    // Verify snapshot exists
+    if (!this.lastSnapshotData || !this.lastSnapshotData.refs) {
+      throw new Error('No snapshot data available. Please run snapshot() command first.');
+    }
+
+    // Clear any existing highlights
+    this.clearExistingOverlay();
+
+    // Create overlay container with absolute positioning covering entire document
+    this.overlayContainer = this.document.createElement('div');
+    this.overlayContainer.id = 'btcp-highlight-overlay';
+    this.overlayContainer.style.cssText = `
+      position: absolute;
+      top: 0;
+      left: 0;
+      width: ${this.document.documentElement.scrollWidth}px;
+      height: ${this.document.documentElement.scrollHeight}px;
+      pointer-events: none;
+      z-index: 999999;
+      contain: layout style paint;
+    `;
+
+    let highlightedCount = 0;
+
+    // Create border overlays and labels for each ref
+    for (const [ref, _refData] of Object.entries(this.lastSnapshotData.refs)) {
+      const element = this.refMap.get(ref);
+
+      // Skip if element no longer exists or is disconnected
+      if (!element || !element.isConnected) {
+        continue;
+      }
+
+      try {
+        // Get current bounding box (element might have moved)
+        const bbox = element.getBoundingClientRect();
+
+        // Skip elements with no dimensions
+        if (bbox.width === 0 && bbox.height === 0) {
+          continue;
+        }
+
+        // Create border overlay
+        const border = this.document.createElement('div');
+        border.className = 'btcp-ref-border';
+        border.dataset.ref = ref;
+        border.style.cssText = `
+          position: absolute;
+          width: ${bbox.width}px;
+          height: ${bbox.height}px;
+          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
+          border: 2px solid rgba(59, 130, 246, 0.8);
+          border-radius: 2px;
+          box-shadow: 0 0 0 1px rgba(59, 130, 246, 0.2);
+          pointer-events: none;
+          will-change: transform;
+          contain: layout style paint;
+        `;
+
+        // Create label
+        const label = this.document.createElement('div');
+        label.className = 'btcp-ref-label';
+        label.dataset.ref = ref;
+        // Extract number from ref (e.g., "@ref:5" -> "5")
+        label.textContent = ref.replace('@ref:', '');
+        label.style.cssText = `
+          position: absolute;
+          transform: translate3d(${bbox.left + this.window.scrollX}px, ${bbox.top + this.window.scrollY}px, 0);
+          background: rgba(59, 130, 246, 0.9);
+          color: white;
+          padding: 2px 6px;
+          border-radius: 3px;
+          font-family: monospace;
+          font-size: 11px;
+          font-weight: bold;
+          box-shadow: 0 2px 4px rgba(0,0,0,0.3);
+          pointer-events: none;
+          white-space: nowrap;
+          will-change: transform;
+          contain: layout style paint;
+        `;
+
+        this.overlayContainer.appendChild(border);
+        this.overlayContainer.appendChild(label);
+        highlightedCount++;
+      } catch (error) {
+        // Skip elements that throw errors
+        continue;
+      }
+    }
+
+    // Inject overlay into page
+    this.document.body.appendChild(this.overlayContainer);
+
+    // Set up scroll listener with rAF throttling
+    let ticking = false;
+    this.scrollListener = () => {
+      if (!ticking) {
+        this.rafId = this.window.requestAnimationFrame(() => {
+          this.updateHighlightPositions();
+          ticking = false;
+        });
+        ticking = true;
+      }
+    };
+
+    // Use passive listener for better scroll performance
+    this.window.addEventListener('scroll', this.scrollListener, { passive: true });
+
+    return { highlighted: highlightedCount };
+  }
+
+  /**
+   * Invalidate snapshot data (called on navigation or manual clear)
+   */
+  public invalidateSnapshot(): void {
+    this.lastSnapshotData = null;
+    this.clearHighlight();
+  }
+
+  /**
+   * Update highlight positions on scroll (GPU-accelerated)
+   */
+  private updateHighlightPositions(): void {
+    if (!this.overlayContainer || !this.lastSnapshotData) {
+      return;
+    }
+
+    // Batch DOM reads
+    const updates: Array<{ element: HTMLElement; x: number; y: number; width?: number; height?: number }> = [];
+
+    // Read phase - get all bounding boxes first
+    const borders = this.overlayContainer.querySelectorAll('.btcp-ref-border');
+    const labels = this.overlayContainer.querySelectorAll('.btcp-ref-label');
+
+    borders.forEach((borderEl) => {
+      const ref = (borderEl as HTMLElement).dataset.ref;
+      if (!ref) return;
+
+      const element = this.refMap.get(ref);
+      if (!element || !element.isConnected) return;
+
+      const bbox = element.getBoundingClientRect();
+      if (bbox.width === 0 && bbox.height === 0) return;
+
+      updates.push({
+        element: borderEl as HTMLElement,
+        x: bbox.left + this.window.scrollX,
+        y: bbox.top + this.window.scrollY,
+        width: bbox.width,
+        height: bbox.height,
+      });
+    });
+
+    labels.forEach((labelEl) => {
+      const ref = (labelEl as HTMLElement).dataset.ref;
+      if (!ref) return;
+
+      const element = this.refMap.get(ref);
+      if (!element || !element.isConnected) return;
+
+      const bbox = element.getBoundingClientRect();
+      if (bbox.width === 0 && bbox.height === 0) return;
+
+      updates.push({
+        element: labelEl as HTMLElement,
+        x: bbox.left + this.window.scrollX,
+        y: bbox.top + this.window.scrollY,
+      });
+    });
+
+    // Write phase - update transforms
+    updates.forEach(({ element, x, y, width, height }) => {
+      element.style.transform = `translate3d(${x}px, ${y}px, 0)`;
+      if (width !== undefined && height !== undefined) {
+        element.style.width = `${width}px`;
+        element.style.height = `${height}px`;
+      }
+    });
+  }
+
+  /**
+   * Remove visual overlay labels
+   */
+  private async clearHighlight(): Promise<{ cleared: true }> {
+    this.clearExistingOverlay();
+    return { cleared: true };
+  }
+
+  /**
+   * Remove existing overlay if it exists
+   */
+  private clearExistingOverlay(): void {
+    // Remove scroll listener
+    if (this.scrollListener) {
+      this.window.removeEventListener('scroll', this.scrollListener);
+      this.scrollListener = null;
+    }
+
+    // Cancel any pending animation frame
+    if (this.rafId !== null) {
+      this.window.cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+
+    // Remove overlay container
+    if (this.overlayContainer && this.overlayContainer.parentNode) {
+      this.overlayContainer.parentNode.removeChild(this.overlayContainer);
+    }
+    this.overlayContainer = null;
+
+    // Also remove any orphaned overlays
+    const existingOverlay = this.document.getElementById('btcp-highlight-overlay');
+    if (existingOverlay && existingOverlay.parentNode) {
+      existingOverlay.parentNode.removeChild(existingOverlay);
+    }
+  }
+
+  // --- Utilities ---
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}