cdp-skill 1.0.8 → 1.0.15

package/src/dom/element-locator.js

@@ -30,13 +30,27 @@ const MAX_TIMEOUT = TIMEOUTS.MAX;
  * @param {Object} session - CDP session
  * @param {Object} [options] - Configuration options
  * @param {number} [options.timeout=30000] - Default timeout in ms
+ * @param {Function} [options.getFrameContext] - Returns contextId when in a non-main frame
  * @returns {Object} Element locator interface
  */
 export function createElementLocator(session, options = {}) {
   if (!session) throw new Error('CDP session is required');
 
+  const getFrameContext = options.getFrameContext || null;
   let defaultTimeout = options.timeout || 30000;
 
+  /**
+   * Build Runtime.evaluate params, injecting contextId when in an iframe.
+   */
+  function evalParams(expression, returnByValue = false) {
+    const params = { expression, returnByValue };
+    if (getFrameContext) {
+      const contextId = getFrameContext();
+      if (contextId) params.contextId = contextId;
+    }
+    return params;
+  }
+
   function validateTimeout(timeout) {
     if (typeof timeout !== 'number' || !Number.isFinite(timeout)) return defaultTimeout;
     if (timeout < 0) return 0;
@@ -59,10 +73,9 @@ export function createElementLocator(session, options = {}) {
 
     let result;
     try {
-      result = await session.send('Runtime.evaluate', {
-        expression: `document.querySelector(${JSON.stringify(selector)})`,
-        returnByValue: false
-      });
+      result = await session.send('Runtime.evaluate',
+        evalParams(`document.querySelector(${JSON.stringify(selector)})`, false)
+      );
     } catch (error) {
       throw connectionError(error.message, 'Runtime.evaluate (querySelector)');
     }
@@ -89,10 +102,9 @@ export function createElementLocator(session, options = {}) {
 
     let result;
     try {
-      result = await session.send('Runtime.evaluate', {
-        expression: `Array.from(document.querySelectorAll(${JSON.stringify(selector)}))`,
-        returnByValue: false
-      });
+      result = await session.send('Runtime.evaluate',
+        evalParams(`Array.from(document.querySelectorAll(${JSON.stringify(selector)}))`, false)
+      );
     } catch (error) {
       throw connectionError(error.message, 'Runtime.evaluate (querySelectorAll)');
     }
@@ -175,10 +187,9 @@ export function createElementLocator(session, options = {}) {
     while (Date.now() - startTime < validatedTimeout) {
       let result;
       try {
-        result = await session.send('Runtime.evaluate', {
-          expression: checkExpr,
-          returnByValue: true
-        });
+        result = await session.send('Runtime.evaluate',
+          evalParams(checkExpr, true)
+        );
       } catch (error) {
         throw connectionError(error.message, 'Runtime.evaluate (waitForText)');
       }
@@ -278,10 +289,9 @@ export function createElementLocator(session, options = {}) {
 
     let result;
     try {
-      result = await session.send('Runtime.evaluate', {
-        expression,
-        returnByValue: false
-      });
+      result = await session.send('Runtime.evaluate',
+        evalParams(expression, false)
+      );
     } catch (error) {
       throw connectionError(error.message, 'Runtime.evaluate (queryByRole)');
     }
@@ -403,10 +413,9 @@ export function createElementLocator(session, options = {}) {
 
     let result;
     try {
-      result = await session.send('Runtime.evaluate', {
-        expression,
-        returnByValue: false
-      });
+      result = await session.send('Runtime.evaluate',
+        evalParams(expression, false)
+      );
     } catch (error) {
       throw connectionError(error.message, 'Runtime.evaluate (findElementByText)');
     }
@@ -514,10 +523,9 @@ export function createElementLocator(session, options = {}) {
 
     let result;
     try {
-      result = await session.send('Runtime.evaluate', {
-        expression,
-        returnByValue: false
-      });
+      result = await session.send('Runtime.evaluate',
+        evalParams(expression, false)
+      );
     } catch (error) {
       throw connectionError(error.message, 'Runtime.evaluate (findElementByTextWithinSelector)');
     }
@@ -582,6 +590,7 @@ export function createElementLocator(session, options = {}) {
     waitForElementByText,
     getBoundingBox,
     getDefaultTimeout: () => defaultTimeout,
-    setDefaultTimeout: (timeout) => { defaultTimeout = validateTimeout(timeout); }
+    setDefaultTimeout: (timeout) => { defaultTimeout = validateTimeout(timeout); },
+    get getFrameContext() { return getFrameContext; }
   };
 }

package/src/dom/fill-executor.js

@@ -16,6 +16,7 @@
 import { createActionabilityChecker } from './actionability.js';
 import { createElementValidator } from './element-validator.js';
 import { createReactInputFiller } from './react-filler.js';
+import { createLazyResolver } from './LazyResolver.js';
 import {
   sleep,
   elementNotFoundError,
@@ -31,50 +32,95 @@ import {
  * @param {Object} elementLocator - Element locator instance
  * @param {Object} inputEmulator - Input emulator instance
  * @param {Object} [ariaSnapshot] - Optional ARIA snapshot instance
+ * @param {Object} [options] - Configuration options
+ * @param {Function} [options.getFrameContext] - Returns contextId when in a non-main frame
  * @returns {Object} Fill executor interface
  */
-export function createFillExecutor(session, elementLocator, inputEmulator, ariaSnapshot = null) {
+export function createFillExecutor(session, elementLocator, inputEmulator, ariaSnapshot = null, options = {}) {
   if (!session) throw new Error('CDP session is required');
   if (!elementLocator) throw new Error('Element locator is required');
   if (!inputEmulator) throw new Error('Input emulator is required');
 
+  const getFrameContext = options.getFrameContext || null;
   const actionabilityChecker = createActionabilityChecker(session);
   const elementValidator = createElementValidator(session);
   const reactInputFiller = createReactInputFiller(session);
+  const lazyResolver = createLazyResolver(session, { getFrameContext });
 
-  async function fillByRef(ref, value, opts = {}) {
-    const { clear = true, react = false } = opts;
-
-    if (!ariaSnapshot) {
-      throw new Error('ariaSnapshot is required for ref-based fills');
+  /**
+   * Build Runtime.evaluate params, injecting contextId when in an iframe.
+   */
+  function evalParams(expression, returnByValue = false) {
+    const params = { expression, returnByValue };
+    if (getFrameContext) {
+      const contextId = getFrameContext();
+      if (contextId) params.contextId = contextId;
     }
+    return params;
+  }
 
-    const refInfo = await ariaSnapshot.getElementByRef(ref);
-    if (!refInfo) {
-      throw elementNotFoundError(`ref:${ref}`, 0);
+  /**
+   * Select all and fill with value, handling the empty-string case.
+   * When value is "" and clear is true, presses Delete after selectAll
+   * to actually remove the selected content (insertText("") is a no-op).
+   */
+  async function selectAndFill(value, clear) {
+    if (clear) {
+      await inputEmulator.selectAll();
     }
-
-    if (refInfo.stale) {
-      throw new Error(`Element ref:${ref} is no longer attached to the DOM. Page content may have changed. Run 'snapshot' again to get fresh refs.`);
+    if (value === '' && clear) {
+      // insertText("") is a no-op in CDP — press Delete to remove selected text
+      await inputEmulator.press('Delete');
+      // Dispatch input/change events so frameworks (React, Vue, etc.) react to the clear
+      await session.send('Runtime.evaluate', evalParams(`
+        (function() {
+          const el = document.activeElement;
+          if (el) {
+            el.dispatchEvent(new Event('input', { bubbles: true, cancelable: true }));
+            el.dispatchEvent(new Event('change', { bubbles: true, cancelable: true }));
+          }
+        })()
+      `, true));
+    } else {
+      await inputEmulator.insertText(String(value));
     }
+  }
 
-    if (refInfo.isVisible === false) {
-      throw new Error(`Element ref:${ref} exists but is not visible. It may be hidden or have zero dimensions.`);
+  async function fillByRef(ref, value, opts = {}) {
+    const { clear = true, react = false } = opts;
+
+    // LAZY RESOLUTION: Always resolve ref from metadata, never rely on cached element
+    // This eliminates stale element errors entirely
+    const resolved = await lazyResolver.resolveRef(ref);
+    if (!resolved) {
+      throw elementNotFoundError(`ref:${ref}`, 0);
     }
 
-    const elementResult = await session.send('Runtime.evaluate', {
-      expression: `(function() {
-        const el = window.__ariaRefs && window.__ariaRefs.get(${JSON.stringify(ref)});
-        return el;
-      })()`,
-      returnByValue: false
+    const objectId = resolved.objectId;
+
+    // Get visibility info using the resolved element
+    const visibilityResult = await session.send('Runtime.callFunctionOn', {
+      objectId,
+      functionDeclaration: `function() {
+        const style = window.getComputedStyle(this);
+        const rect = this.getBoundingClientRect();
+        return {
+          isVisible: style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0' && rect.width > 0 && rect.height > 0,
+          box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+        };
+      }`,
+      returnByValue: true
     });
 
-    if (!elementResult.result.objectId) {
-      throw elementNotFoundError(`ref:${ref}`, 0);
-    }
+    const refInfo = {
+      box: visibilityResult.result?.value?.box || resolved.box,
+      isVisible: visibilityResult.result?.value?.isVisible ?? true
+    };
 
-    const objectId = elementResult.result.objectId;
+    if (refInfo.isVisible === false) {
+      await releaseObject(session, objectId);
+      throw new Error(`Element ref:${ref} exists but is not visible. It may be hidden or have zero dimensions.`);
+    }
 
     const editableCheck = await elementValidator.isEditable(objectId);
     if (!editableCheck.editable) {
@@ -106,11 +152,7 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
         functionDeclaration: `function() { this.focus(); }`
       });
 
-      if (clear) {
-        await inputEmulator.selectAll();
-      }
-
-      await inputEmulator.insertText(String(value));
+      await selectAndFill(value, clear);
 
       return { filled: true, ref, method: 'insertText' };
     } finally {
@@ -153,11 +195,7 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
         functionDeclaration: `function() { this.focus(); }`
       });
 
-      if (clear) {
-        await inputEmulator.selectAll();
-      }
-
-      await inputEmulator.insertText(String(value));
+      await selectAndFill(value, clear);
 
       return { filled: true, selector, method: 'insertText' };
     } catch (e) {
@@ -277,10 +315,9 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
 
     let result;
     try {
-      result = await session.send('Runtime.evaluate', {
-        expression,
-        returnByValue: false
-      });
+      result = await session.send('Runtime.evaluate',
+        evalParams(expression, false)
+      );
     } catch (error) {
       throw connectionError(error.message, 'Runtime.evaluate (findInputByLabel)');
     }
@@ -383,11 +420,7 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
         functionDeclaration: `function() { this.focus(); }`
       });
 
-      if (clear) {
-        await inputEmulator.selectAll();
-      }
-
-      await inputEmulator.insertText(String(value));
+      await selectAndFill(value, clear);
 
       return { filled: true, label, method: 'insertText', foundBy: foundMethod };
     } catch (e) {
@@ -405,9 +438,9 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
       throw new Error('Fill requires value');
     }
 
-    // Detect if selector looks like a versioned ref (s{N}e{M})
-    // This allows {"fill": {"selector": "s1e1", "value": "..."}} to work like {"fill": {"ref": "s1e1", "value": "..."}}
-    if (!ref && selector && /^s\d+e\d+$/.test(selector)) {
+    // Detect if selector looks like a versioned ref (f{frameId}s{N}e{M})
+    // This allows {"fill": {"selector": "f0s1e1", "value": "..."}} to work like {"fill": {"ref": "f0s1e1", "value": "..."}}
+    if (!ref && selector && /^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(selector)) {
       ref = selector;
     }
 
@@ -430,7 +463,7 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
 
   async function executeBatch(params) {
     if (!params || typeof params !== 'object') {
-      throw new Error('fillForm requires an object mapping selectors to values');
+      throw new Error('fill batch requires an object mapping selectors to values');
     }
 
     // Support both formats:
@@ -450,7 +483,7 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
 
     const entries = Object.entries(fields);
     if (entries.length === 0) {
-      throw new Error('fillForm requires at least one field');
+      throw new Error('fill batch requires at least one field');
     }
 
     const results = [];
@@ -458,8 +491,8 @@ export function createFillExecutor(session, elementLocator, inputEmulator, ariaS
 
     for (const [selector, value] of entries) {
       try {
-        // Match versioned ref format s{N}e{M}
-        const isRef = /^s\d+e\d+$/.test(selector);
+        // Match versioned ref format f{frameId}s{N}e{M}
+        const isRef = /^f(\d+|\[[^\]]+\])s\d+e\d+$/.test(selector);
 
         if (isRef) {
           await fillByRef(selector, value, { clear: true, react: useReact });

package/src/dom/index.js

@@ -76,6 +76,9 @@ export { createKeyboardExecutor } from './keyboard-executor.js';
 // Wait executor (waiting operations)
 export { createWaitExecutor } from './wait-executor.js';
 
+// Lazy resolver (stateless element resolution)
+export { createLazyResolver } from './LazyResolver.js';
+
 // ============================================================================
 // Convenience Functions
 // ============================================================================

package/src/page/dialog-handler.js

@@ -0,0 +1,119 @@
+/**
+ * Dialog Handler Module
+ * Handles JavaScript alerts, confirms, and prompts
+ *
+ * PUBLIC EXPORTS:
+ * - createDialogHandler(session) - Factory for dialog handler
+ *
+ * @module cdp-skill/page/dialog-handler
+ */
+
+/**
+ * Create a dialog handler for JavaScript dialogs
+ * @param {import('../types.js').CDPSession} session - CDP session
+ * @returns {Object} Dialog handler interface
+ */
+export function createDialogHandler(session) {
+  let dialogCallback = null;
+  let boundHandler = null;
+  const responseQueue = [];
+
+  function onDialogOpening(params) {
+    const { type, message, defaultPrompt } = params;
+
+    // Default behavior: accept all dialogs
+    let accept = true;
+    let promptText = undefined;
+
+    // Check if there's a queued response
+    if (responseQueue.length > 0) {
+      const queued = responseQueue.shift();
+      accept = queued.accept !== false;
+      promptText = queued.promptText;
+    } else if (dialogCallback) {
+      // If custom callback is set, use it
+      const result = dialogCallback({ type, message, defaultPrompt });
+      accept = result.accept !== false;
+      promptText = result.promptText;
+    } else {
+      // Auto-accept with reasonable defaults for prompts
+      if (type === 'prompt') {
+        // Use defaultPrompt if available
+        // Otherwise, for test automation purposes, use a reasonable default
+        if (defaultPrompt !== undefined && defaultPrompt.length > 0) {
+          promptText = defaultPrompt;
+        } else if (message && message.toLowerCase().includes('prompt')) {
+          // For prompt dialogs asking for input, use a test value
+          promptText = 'Hello CDP';
+        } else {
+          promptText = '';
+        }
+      }
+    }
+
+    // Handle the dialog
+    session.send('Page.handleJavaScriptDialog', {
+      accept,
+      promptText
+    }).catch(err => {
+      // Ignore errors - dialog may have been already handled
+    });
+  }
+
+  /**
+   * Enable dialog handling
+   * @param {Function} [callback] - Optional callback to customize dialog handling
+   * @returns {Promise<void>}
+   */
+  async function enable(callback = null) {
+    dialogCallback = callback;
+
+    if (!boundHandler) {
+      boundHandler = onDialogOpening;
+      session.on('Page.javascriptDialogOpening', boundHandler);
+    }
+
+    // Enable page domain if not already enabled
+    try {
+      await session.send('Page.enable');
+    } catch (err) {
+      // Ignore if already enabled
+    }
+  }
+
+  /**
+   * Disable dialog handling
+   * @returns {Promise<void>}
+   */
+  async function disable() {
+    if (boundHandler) {
+      session.off('Page.javascriptDialogOpening', boundHandler);
+      boundHandler = null;
+    }
+    dialogCallback = null;
+  }
+
+  /**
+   * Set a custom dialog handler
+   * @param {Function} callback - Callback({type, message, defaultPrompt}) => {accept, promptText}
+   */
+  function setHandler(callback) {
+    dialogCallback = callback;
+  }
+
+  /**
+   * Queue a response for the next dialog
+   * @param {boolean} accept - Whether to accept the dialog
+   * @param {string} [promptText] - Text to enter for prompts
+   */
+  function queueResponse(accept, promptText) {
+    responseQueue.push({ accept, promptText });
+  }
+
+  return {
+    enable,
+    disable,
+    setHandler,
+    queueResponse
+  };
+}