btcp-browser-agent 0.1.0 → 0.1.1

package/packages/core/dist/actions.js

@@ -0,0 +1,940 @@
+/**
+ * @btcp/core - DOM Actions
+ *
+ * Element interaction handlers using native browser APIs.
+ */
+import { createSnapshot } from './snapshot.js';
+import { DetailedError, createElementNotFoundError, createElementNotCompatibleError, createTimeoutError, createInvalidParametersError, } from './errors.js';
+/**
+ * DOM Actions executor
+ */
+export class DOMActions {
+    document;
+    window;
+    refMap;
+    lastSnapshotData = null;
+    overlayContainer = null;
+    scrollListener = null;
+    rafId = null;
+    constructor(doc, win, refMap) {
+        this.document = doc;
+        this.window = win;
+        this.refMap = refMap;
+    }
+    /**
+     * Execute a command and return a response
+     */
+    async execute(command) {
+        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 };
+        }
+    }
+    async dispatch(command) {
+        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.action}`);
+        }
+    }
+    // --- Element Resolution ---
+    getElement(selector) {
+        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
+     */
+    findSimilarSelectors(selector) {
+        const results = [];
+        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
+     */
+    getNearbyInteractiveElements() {
+        const results = [];
+        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.value?.substring(0, 30) ||
+                            el.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
+     */
+    getAvailableActionsForElement(element) {
+        const actions = [];
+        // 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;
+    }
+    queryElement(selector) {
+        // Check if it's a ref
+        if (selector.startsWith('@ref:')) {
+            return this.refMap.get(selector);
+        }
+        // CSS selector
+        return this.document.querySelector(selector);
+    }
+    queryElements(selector) {
+        if (selector.startsWith('@ref:')) {
+            const el = this.refMap.get(selector);
+            return el ? [el] : [];
+        }
+        return Array.from(this.document.querySelectorAll(selector));
+    }
+    // --- Actions ---
+    async click(selector, options = {}) {
+        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 = {
+            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 };
+    }
+    async dblclick(selector) {
+        const element = this.getElement(selector);
+        element.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }));
+        return { clicked: true };
+    }
+    async type(selector, text, options = {}) {
+        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 };
+    }
+    async fill(selector, value) {
+        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 };
+    }
+    async clear(selector) {
+        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 };
+    }
+    async check(selector) {
+        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 };
+    }
+    async uncheck(selector) {
+        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 };
+    }
+    async select(selector, values) {
+        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 };
+    }
+    async focus(selector) {
+        const element = this.getElement(selector);
+        if (element instanceof HTMLElement) {
+            element.focus();
+        }
+        return { focused: true };
+    }
+    async blur(selector) {
+        const element = this.getElement(selector);
+        if (element instanceof HTMLElement) {
+            element.blur();
+        }
+        return { blurred: true };
+    }
+    async hover(selector) {
+        const element = this.getElement(selector);
+        element.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+        element.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+        return { hovered: true };
+    }
+    async scroll(selector, options) {
+        // 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 };
+    }
+    async scrollIntoView(selector, block = 'center') {
+        const element = this.getElement(selector);
+        element.scrollIntoView({ behavior: 'smooth', block });
+        return { scrolled: true };
+    }
+    async snapshot(options) {
+        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;
+    }
+    async querySelector(selector) {
+        const element = this.queryElement(selector);
+        if (!element) {
+            return { found: false };
+        }
+        const ref = this.refMap.generateRef(element);
+        return { found: true, ref };
+    }
+    async querySelectorAll(selector) {
+        const elements = this.queryElements(selector);
+        const refs = elements.map((el) => this.refMap.generateRef(el));
+        return { count: elements.length, refs };
+    }
+    async getText(selector) {
+        const element = this.getElement(selector);
+        return { text: element.textContent };
+    }
+    async getAttribute(selector, attribute) {
+        const element = this.getElement(selector);
+        return { value: element.getAttribute(attribute) };
+    }
+    async getProperty(selector, property) {
+        const element = this.getElement(selector);
+        return { value: element[property] };
+    }
+    async getBoundingBox(selector) {
+        const element = this.getElement(selector);
+        const rect = element.getBoundingClientRect();
+        return {
+            box: {
+                x: rect.x,
+                y: rect.y,
+                width: rect.width,
+                height: rect.height,
+            },
+        };
+    }
+    async isVisible(selector) {
+        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 };
+    }
+    async isEnabled(selector) {
+        const element = this.getElement(selector);
+        const enabled = !element.disabled;
+        return { enabled };
+    }
+    async isChecked(selector) {
+        const element = this.getElement(selector);
+        const checked = element.checked ?? false;
+        return { checked };
+    }
+    async press(key, selector, modifiers = []) {
+        const target = selector
+            ? this.getElement(selector)
+            : this.document.activeElement || this.document.body;
+        const eventInit = {
+            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 };
+    }
+    async keyDown(key) {
+        const target = this.document.activeElement || this.document.body;
+        target.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true }));
+        return { down: true };
+    }
+    async keyUp(key) {
+        const target = this.document.activeElement || this.document.body;
+        target.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
+        return { up: true };
+    }
+    async wait(selector, options = {}) {
+        const { state = 'visible', timeout = 5000 } = options;
+        if (!selector) {
+            await this.sleep(timeout);
+            return { waited: true };
+        }
+        const startTime = Date.now();
+        let lastState;
+        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.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.disabled;
+                    break;
+            }
+            if (conditionMet) {
+                return { waited: true };
+            }
+            await this.sleep(100);
+        }
+        // Provide detailed timeout error with current state
+        throw createTimeoutError(selector, state, lastState);
+    }
+    async evaluate(script, args) {
+        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
+     */
+    async validateElement(selector, options = {}) {
+        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.disabled,
+        };
+        // Check type compatibility
+        let compatible = true;
+        let suggestion;
+        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 = {
+                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
+     */
+    async validateRefs(refs) {
+        const valid = [];
+        const invalid = [];
+        const reasons = {};
+        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
+     */
+    async highlight() {
+        // 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)
+     */
+    invalidateSnapshot() {
+        this.lastSnapshotData = null;
+        this.clearHighlight();
+    }
+    /**
+     * Update highlight positions on scroll (GPU-accelerated)
+     */
+    updateHighlightPositions() {
+        if (!this.overlayContainer || !this.lastSnapshotData) {
+            return;
+        }
+        // Batch DOM reads
+        const updates = [];
+        // 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.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,
+                x: bbox.left + this.window.scrollX,
+                y: bbox.top + this.window.scrollY,
+                width: bbox.width,
+                height: bbox.height,
+            });
+        });
+        labels.forEach((labelEl) => {
+            const ref = labelEl.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,
+                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
+     */
+    async clearHighlight() {
+        this.clearExistingOverlay();
+        return { cleared: true };
+    }
+    /**
+     * Remove existing overlay if it exists
+     */
+    clearExistingOverlay() {
+        // 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 ---
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=actions.js.map