cdp-skill 1.0.8 → 1.0.15

package/src/page/page-controller.js

@@ -21,6 +21,7 @@ import {
 } from '../utils.js';
 
 import { TIMEOUTS } from '../constants.js';
+import { createDialogHandler } from './dialog-handler.js';
 
 const MAX_TIMEOUT = TIMEOUTS.MAX;
 
@@ -39,9 +40,13 @@ export const WaitCondition = Object.freeze({
 /**
  * Create a page controller for navigation and lifecycle events
  * @param {import('../types.js').CDPSession} cdpClient - CDP client with send/on/off methods
+ * @param {Object} [options] - Options
+ * @param {function(Object): void} [options.onFrameChanged] - Called when frame context changes (for persistence)
+ * @param {function(): Object|null} [options.getSavedFrameState] - Returns saved frame state (for restoration)
  * @returns {Object} Page controller interface
  */
-export function createPageController(cdpClient) {
+export function createPageController(cdpClient, options = {}) {
+  const { onFrameChanged, getSavedFrameState } = options;
   let mainFrameId = null;
   let currentFrameId = null;
   let currentExecutionContextId = null;
@@ -54,6 +59,7 @@ export function createPageController(cdpClient) {
   const networkIdleDelay = 500;
   let navigationInProgress = false;
   let currentNavigationAbort = null;
+  const dialogHandler = createDialogHandler(cdpClient);
   let currentNavigationUrl = null;
   let pageCrashed = false;
   const crashWaiters = new Set();
@@ -221,6 +227,54 @@ export function createPageController(cdpClient) {
     });
   }
 
+  /**
+   * Best-effort network settle — waits briefly for network to quiet down.
+   * Unlike waitForNetworkQuiet, this NEVER throws on timeout. It resolves
+   * silently so callers (snapshot, post-navigation) don't fail on sites
+   * with persistent connections or long-polling.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.timeout=2000] - Max time to wait
+   * @param {number} [options.idleTime=300] - Idle window to consider settled
+   * @returns {Promise<{settled: boolean, pendingCount: number}>}
+   */
+  function waitForNetworkSettle(options = {}) {
+    const { timeout = 2000, idleTime = 300 } = options;
+
+    return new Promise((resolve) => {
+      // Already idle long enough?
+      if (pendingRequests.size === 0 && (Date.now() - lastNetworkActivity) >= idleTime) {
+        resolve({ settled: true, pendingCount: 0 });
+        return;
+      }
+
+      let resolved = false;
+      let timeoutId = null;
+      let checkInterval = null;
+
+      const finish = (settled) => {
+        if (resolved) return;
+        resolved = true;
+        if (timeoutId) clearTimeout(timeoutId);
+        if (checkInterval) clearInterval(checkInterval);
+        networkIdleWaiters.delete(waiter);
+        resolve({ settled, pendingCount: pendingRequests.size });
+      };
+
+      const waiter = () => finish(true);
+      networkIdleWaiters.add(waiter);
+
+      timeoutId = setTimeout(() => finish(false), timeout);
+
+      checkInterval = setInterval(() => {
+        if (resolved) { clearInterval(checkInterval); return; }
+        if (pendingRequests.size === 0 && (Date.now() - lastNetworkActivity) >= idleTime) {
+          finish(true);
+        }
+      }, 50);
+    });
+  }
+
   /**
    * Get current network status
    * @returns {{pendingCount: number, totalRequests: number, lastActivity: number, isIdle: boolean}}
@@ -360,6 +414,9 @@ export function createPageController(cdpClient) {
       cdpClient.send('Inspector.enable')
     ]);
 
+    // Enable dialog handling for JavaScript alerts, confirms, and prompts
+    await dialogHandler.enable();
+
     const { frameTree } = await cdpClient.send('Page.getFrameTree');
     mainFrameId = frameTree.frame.id;
     currentFrameId = mainFrameId;
@@ -388,6 +445,56 @@ export function createPageController(cdpClient) {
     addListener('Network.loadingFinished', onRequestFinished);
     addListener('Network.loadingFailed', onRequestFinished);
     addListener('Inspector.targetCrashed', onTargetCrashed);
+
+    // Restore persisted frame context from a previous CLI invocation
+    if (getSavedFrameState) {
+      const saved = getSavedFrameState();
+      if (saved && saved.frameId && saved.frameId !== mainFrameId) {
+        // Verify the saved frame still exists in the frame tree
+        function findAllFrames(node) {
+          const frames = [node];
+          if (node.childFrames) {
+            for (const child of node.childFrames) {
+              frames.push(...findAllFrames(child));
+            }
+          }
+          return frames;
+        }
+        const allFrames = findAllFrames(frameTree);
+        const savedFrame = allFrames.find(f => f.frame.id === saved.frameId);
+
+        if (savedFrame) {
+          currentFrameId = saved.frameId;
+          // Try to use the saved contextId if it's still in our context map
+          const knownContextId = frameExecutionContexts.get(saved.frameId);
+          if (knownContextId) {
+            currentExecutionContextId = knownContextId;
+          } else {
+            // Create a fresh isolated world for this frame
+            try {
+              const { executionContextId } = await cdpClient.send('Page.createIsolatedWorld', {
+                frameId: saved.frameId,
+                worldName: 'cdp-automation'
+              });
+              currentExecutionContextId = executionContextId;
+              frameExecutionContexts.set(saved.frameId, executionContextId);
+            } catch {
+              // Frame context restoration failed — fall back to main frame
+              currentFrameId = mainFrameId;
+              currentExecutionContextId = frameExecutionContexts.get(mainFrameId) || null;
+              if (onFrameChanged) {
+                onFrameChanged({ frameId: null, contextId: null });
+              }
+            }
+          }
+        } else {
+          // Frame no longer exists — clear stale state
+          if (onFrameChanged) {
+            onFrameChanged({ frameId: null, contextId: null });
+          }
+        }
+      }
+    }
   }
 
   /**
@@ -670,7 +777,13 @@ export function createPageController(cdpClient) {
   }
 
   /**
-   * Get frame tree with all iframes
+   * Get frame tree with all iframes, including cross-origin ones.
+   *
+   * Page.getFrameTree only returns same-origin frames. Cross-origin iframes
+   * live in separate renderer processes and are invisible to that API.
+   * We supplement the CDP tree by querying the DOM for all <iframe> elements
+   * and merging any that aren't already represented.
+   *
    * @returns {Promise<{mainFrameId: string, currentFrameId: string, frames: Array}>}
    */
   async function getFrameTree() {
@@ -694,10 +807,60 @@ export function createPageController(cdpClient) {
       return frames;
     }
 
+    const frames = flattenFrames(frameTree);
+
+    // Discover cross-origin iframes via DOM query
+    try {
+      const domResult = await cdpClient.send('Runtime.evaluate', {
+        expression: `
+          (function() {
+            const iframes = document.querySelectorAll('iframe');
+            return Array.from(iframes).map(function(el, i) {
+              var src = el.src || el.getAttribute('src') || '';
+              var name = el.name || el.id || '';
+              var crossOrigin = false;
+              try { var _d = el.contentDocument; } catch(e) { crossOrigin = true; }
+              if (!el.contentDocument) crossOrigin = true;
+              return { index: i, src: src, name: name, crossOrigin: crossOrigin };
+            });
+          })()
+        `,
+        returnByValue: true
+      });
+
+      const domIframes = domResult.result?.value;
+      if (Array.isArray(domIframes)) {
+        for (const iframe of domIframes) {
+          if (!iframe.crossOrigin) continue;
+
+          // Check if this iframe is already in the CDP frame tree
+          const alreadyListed = frames.some(f =>
+            f.parentId && (
+              (iframe.src && f.url === iframe.src) ||
+              (iframe.name && f.name === iframe.name)
+            )
+          );
+
+          if (!alreadyListed) {
+            frames.push({
+              frameId: `cross-origin-${iframe.index}`,
+              url: iframe.src || 'about:blank',
+              name: iframe.name || null,
+              parentId: mainFrameId,
+              depth: 1,
+              crossOrigin: true
+            });
+          }
+        }
+      }
+    } catch {
+      // DOM query failed — return CDP-only tree
+    }
+
     return {
       mainFrameId,
       currentFrameId,
-      frames: flattenFrames(frameTree)
+      frames
     };
   }
 
@@ -830,6 +993,11 @@ export function createPageController(cdpClient) {
       result.warning = warning;
     }
 
+    // Persist frame state across CLI invocations
+    if (onFrameChanged) {
+      onFrameChanged({ frameId: currentFrameId, contextId: currentExecutionContextId });
+    }
+
     return result;
   }
 
@@ -841,6 +1009,11 @@ export function createPageController(cdpClient) {
     currentFrameId = mainFrameId;
     currentExecutionContextId = frameExecutionContexts.get(mainFrameId) || null;
 
+    // Clear persisted frame state (back to main)
+    if (onFrameChanged) {
+      onFrameChanged({ frameId: null, contextId: null });
+    }
+
     const { frameTree } = await cdpClient.send('Page.getFrameTree');
 
     return {
@@ -850,6 +1023,63 @@ export function createPageController(cdpClient) {
     };
   }
 
+  /**
+   * Get the current frame execution context ID (if in a non-main frame).
+   * Used for dependency injection into modules that need frame-aware evaluation.
+   * @returns {number|null} contextId for current frame, or null if in main frame
+   */
+  function getFrameContext() {
+    if (currentFrameId !== mainFrameId && currentExecutionContextId) {
+      return currentExecutionContextId;
+    }
+    return null;
+  }
+
+  /**
+   * Get the current frame identifier for ref generation.
+   * Returns 'f0' for main frame, 'f1', 'f2', etc. for iframes by index.
+   * Uses frame name if available for better stability.
+   * @returns {Promise<string>} Frame identifier (e.g., 'f0', 'f1', 'f[frame-name]')
+   */
+  async function getFrameIdentifier() {
+    // Main frame is always f0
+    if (currentFrameId === mainFrameId || !currentFrameId) {
+      return 'f0';
+    }
+
+    // Get frame tree to find index or name
+    const { frameTree } = await cdpClient.send('Page.getFrameTree');
+
+    function findAllChildFrames(node) {
+      const frames = [];
+      if (node.childFrames) {
+        for (const child of node.childFrames) {
+          frames.push(child);
+          frames.push(...findAllChildFrames(child));
+        }
+      }
+      return frames;
+    }
+
+    const childFrames = findAllChildFrames(frameTree);
+
+    // Find current frame
+    for (let i = 0; i < childFrames.length; i++) {
+      if (childFrames[i].frame.id === currentFrameId) {
+        // Prefer name if available (more stable than index)
+        const frameName = childFrames[i].frame.name;
+        if (frameName) {
+          return `f[${frameName}]`;
+        }
+        // Fall back to index (1-based for iframes)
+        return `f${i + 1}`;
+      }
+    }
+
+    // Fallback: unknown frame, use hash of frameId
+    return `f[${currentFrameId.substring(0, 8)}]`;
+  }
+
   /**
    * Execute code in the current frame context
    * @param {string} expression - JavaScript expression
@@ -1106,8 +1336,11 @@ export function createPageController(cdpClient) {
     waitForNavigationEvent,
     withNavigation,
     waitForNetworkQuiet,
+    waitForNetworkSettle,
     getNetworkStatus,
     searchAllFrames,
+    getFrameContext,
+    getFrameIdentifier,
     dispose,
     get mainFrameId() { return mainFrameId; },
     get currentFrameId() { return currentFrameId; },

package/src/runner/context-helpers.js

@@ -6,30 +6,18 @@
  * - buildActionContext(action, params, context) → string - Describes what action was taken
  * - buildCommandContext(steps) → string - Summarizes multi-step commands
  * - captureFailureContext(deps) → Object - Gathers debug info on failure
- * - STEP_TYPES - Array of valid step type names
- * - VISUAL_ACTIONS - Actions that trigger auto-screenshot
+ * - STEP_TYPES - Array of valid step type names (from registry)
+ * - VISUAL_ACTIONS - Actions that trigger auto-screenshot (from registry)
  *
- * DEPENDENCIES: None (pure functions)
+ * DEPENDENCIES:
+ * - ./step-registry.js: getAllStepTypes, getVisualActions
  */
 
-export const STEP_TYPES = [
-  'goto', 'wait', 'click', 'fill', 'fillForm', 'press', 'query', 'queryAll',
-  'inspect', 'scroll', 'console', 'pdf', 'eval', 'snapshot', 'snapshotSearch',
-  'hover', 'viewport', 'cookies', 'back', 'forward', 'waitForNavigation', 'listTabs',
-  'closeTab', 'openTab', 'type', 'select', 'selectOption', 'validate', 'submit',
-  'assert', 'switchToFrame', 'switchToMainFrame', 'listFrames', 'drag', 'formState',
-  'extract', 'getDom', 'getBox', 'fillActive', 'refAt', 'elementsAt', 'elementsNear',
-  'reload', 'pageFunction', 'poll', 'pipeline', 'writeSiteProfile', 'readSiteProfile'
-];
+import { getAllStepTypes, getVisualActions } from './step-registry.js';
 
-// Visual actions that trigger auto-screenshot
-// Actions that should capture a screenshot - anything that interacts with or queries the visible page
-export const VISUAL_ACTIONS = [
-  'goto', 'reload', 'click', 'fill', 'fillForm', 'type', 'hover', 'press', 'scroll', 'wait',  // interactions
-  'snapshot', 'snapshotSearch', 'query', 'queryAll', 'inspect', 'eval', 'extract', 'formState',  // queries
-  'drag', 'select', 'selectOption', 'validate', 'submit', 'assert',  // other page interactions
-  'openTab'  // navigation actions - behave like goto for auto-snapshot
-];
+// Re-export from registry for backwards compatibility
+export const STEP_TYPES = getAllStepTypes();
+export const VISUAL_ACTIONS = getVisualActions();
 
 /**
  * Build action context string for diff summary
@@ -59,8 +47,19 @@ export function buildActionContext(action, params, context) {
     case 'hover': {
       if (typeof params === 'string') return `Hovered over ${params}`;
       if (params?.selector) return `Hovered over ${params.selector}`;
+      if (params?.ref) return `Hovered over [ref=${params.ref}]`;
+      if (params?.text) return `Hovered over "${params.text}"`;
+      if (typeof params?.x === 'number' && typeof params?.y === 'number') return `Hovered over (${params.x}, ${params.y})`;
       return 'Hovered over element';
     }
+    case 'frame': {
+      if (params === 'top') return 'Switched to main frame';
+      if (typeof params === 'string') return `Switched to frame ${params}`;
+      if (typeof params === 'number') return `Switched to frame index ${params}`;
+      if (params?.list) return 'Listed frames';
+      if (params?.name) return `Switched to frame "${params.name}"`;
+      return 'Frame operation';
+    }
     case 'fill':
     case 'type': {
       if (params?.selector) return `Typed in ${params.selector}`;
@@ -93,8 +92,8 @@ export function buildCommandContext(steps) {
   if (actions.includes('hover')) return 'Hovered';
   if (actions.includes('fill') || actions.includes('type')) return 'Typed';
   if (actions.includes('press')) return 'Pressed key';
-  if (actions.includes('goto') || actions.includes('openTab')) return 'Navigated';
-  if (actions.includes('select')) return 'Selected';
+  if (actions.includes('goto') || actions.includes('newTab')) return 'Navigated';
+  if (actions.includes('selectText')) return 'Selected';
   if (actions.includes('drag')) return 'Dragged';
 
   // Default: list the actions
@@ -120,10 +119,7 @@ export async function captureFailureContext(deps, options = {}) {
 
   try {
     // Get page title
-    const titleResult = await pageController.session.send('Runtime.evaluate', {
-      expression: 'document.title',
-      returnByValue: true
-    });
+    const titleResult = await pageController.evaluateInFrame('document.title');
     context.title = titleResult.result.value || '';
   } catch {
     context.title = null;
@@ -131,10 +127,7 @@ export async function captureFailureContext(deps, options = {}) {
 
   try {
     // Get current URL
-    const urlResult = await pageController.session.send('Runtime.evaluate', {
-      expression: 'window.location.href',
-      returnByValue: true
-    });
+    const urlResult = await pageController.evaluateInFrame('window.location.href');
     context.url = urlResult.result.value || '';
   } catch {
     context.url = null;
@@ -142,14 +135,11 @@ export async function captureFailureContext(deps, options = {}) {
 
   try {
     // Get scroll position
-    const scrollResult = await pageController.session.send('Runtime.evaluate', {
-      expression: `({
+    const scrollResult = await pageController.evaluateInFrame(`({
         x: window.scrollX || document.documentElement.scrollLeft,
         y: window.scrollY || document.documentElement.scrollTop,
         maxY: Math.max(document.body.scrollHeight, document.documentElement.scrollHeight) - window.innerHeight
-      })`,
-      returnByValue: true
-    });
+      })`);
     const scroll = scrollResult.result.value;
     context.scrollPosition = {
       x: scroll.x,
@@ -163,8 +153,7 @@ export async function captureFailureContext(deps, options = {}) {
 
   try {
     // Get visible buttons with refs (limit 8)
-    const buttonsResult = await pageController.session.send('Runtime.evaluate', {
-      expression: `
+    const buttonsResult = await pageController.evaluateInFrame(`
         (function() {
           const buttons = Array.from(document.querySelectorAll('button, input[type="button"], input[type="submit"], [role="button"]'));
           return buttons
@@ -193,9 +182,7 @@ export async function captureFailureContext(deps, options = {}) {
               return { text, selector, ref };
             });
         })()
-      `,
-      returnByValue: true
-    });
+      `);
     context.visibleButtons = buttonsResult.result.value || [];
   } catch {
     context.visibleButtons = [];
@@ -203,8 +190,7 @@ export async function captureFailureContext(deps, options = {}) {
 
   try {
     // Get visible links (limit 5)
-    const linksResult = await pageController.session.send('Runtime.evaluate', {
-      expression: `
+    const linksResult = await pageController.evaluateInFrame(`
         (function() {
           const links = Array.from(document.querySelectorAll('a[href]'));
           return links
@@ -219,9 +205,7 @@ export async function captureFailureContext(deps, options = {}) {
               href: a.href ? a.href.substring(0, 100) : ''
             }));
         })()
-      `,
-      returnByValue: true
-    });
+      `);
     context.visibleLinks = linksResult.result.value || [];
   } catch {
     context.visibleLinks = [];
@@ -229,8 +213,7 @@ export async function captureFailureContext(deps, options = {}) {
 
   try {
     // Get any visible error messages or alerts
-    const errorsResult = await pageController.session.send('Runtime.evaluate', {
-      expression: `
+    const errorsResult = await pageController.evaluateInFrame(`
         (function() {
           const errorSelectors = [
             '.error', '.alert', '.warning', '.message',
@@ -252,9 +235,7 @@ export async function captureFailureContext(deps, options = {}) {
           }
           return errors.slice(0, 3);
         })()
-      `,
-      returnByValue: true
-    });
+      `);
     context.visibleErrors = errorsResult.result.value || [];
   } catch {
     context.visibleErrors = [];
@@ -264,8 +245,7 @@ export async function captureFailureContext(deps, options = {}) {
   if (failedSelector || failedText) {
     try {
       const searchTerm = failedText || failedSelector;
-      const nearMatchesResult = await pageController.session.send('Runtime.evaluate', {
-        expression: `
+      const nearMatchesResult = await pageController.evaluateInFrame(`
           (function() {
             const searchTerm = ${JSON.stringify(searchTerm)}.toLowerCase();
             const candidates = [];
@@ -322,9 +302,7 @@ export async function captureFailureContext(deps, options = {}) {
             candidates.sort((a, b) => b.score - a.score);
             return candidates.slice(0, 5);
           })()
-        `,
-        returnByValue: true
-      });
+        `);
       context.nearMatches = nearMatchesResult.result.value || [];
     } catch {
       context.nearMatches = [];

package/src/runner/execute-dynamic.js

@@ -53,7 +53,7 @@ function processSerializedResult(raw) {
  * @returns {Promise<Object>} serialized return value
  */
 export async function executePageFunction(pageController, params) {
-  const fn = typeof params === 'string' ? params : params.fn;
+  const fn = typeof params === 'string' ? params : (params.fn || params.expression);
   const useRefs = typeof params === 'object' && params.refs === true;
   const timeout = typeof params === 'object' && typeof params.timeout === 'number'
     ? params.timeout : null;
@@ -150,11 +150,11 @@ export async function executePoll(pageController, params) {
     const rawVal = result.result.value;
     const isTruthy = rawVal !== null && rawVal !== undefined &&
       rawVal !== false && rawVal !== 0 && rawVal !== '' &&
-      !(typeof rawVal === 'object' && rawVal.type === 'null') &&
-      !(typeof rawVal === 'object' && rawVal.type === 'undefined') &&
-      !(typeof rawVal === 'object' && rawVal.type === 'boolean' && rawVal.value === false) &&
-      !(typeof rawVal === 'object' && rawVal.type === 'number' && rawVal.value === 0) &&
-      !(typeof rawVal === 'object' && rawVal.type === 'string' && rawVal.value === '');
+      !(typeof rawVal === 'object' && rawVal !== null && rawVal.type === 'null') &&
+      !(typeof rawVal === 'object' && rawVal !== null && rawVal.type === 'undefined') &&
+      !(typeof rawVal === 'object' && rawVal !== null && rawVal.type === 'boolean' && rawVal.value === false) &&
+      !(typeof rawVal === 'object' && rawVal !== null && rawVal.type === 'number' && rawVal.value === 0) &&
+      !(typeof rawVal === 'object' && rawVal !== null && rawVal.type === 'string' && rawVal.value === '');
 
     if (isTruthy) {
       return { resolved: true, value: processed, elapsed: Date.now() - start };
@@ -393,7 +393,8 @@ export async function loadSiteProfile(domain) {
  */
 export async function executeWriteSiteProfile(params) {
   if (!params || !params.domain || !params.content) {
-    throw new Error('writeSiteProfile requires domain and content');
+    const providedKeys = params ? Object.keys(params).join(', ') : 'none';
+    throw new Error(`writeSiteProfile requires domain and content (got keys: ${providedKeys})`);
   }
 
   const clean = sanitizeDomain(params.domain);

package/src/runner/execute-form.js

@@ -47,8 +47,7 @@ export async function executeExtract(deps, params) {
     throw new Error('extract requires a selector');
   }
 
-  const result = await session.send('Runtime.evaluate', {
-    expression: `
+  const extractExpr = `
       (function() {
         const selector = ${JSON.stringify(selector)};
         const typeHint = ${JSON.stringify(type)};
@@ -160,11 +159,15 @@ export async function executeExtract(deps, params) {
           };
         }
 
-        return { error: 'Could not detect data type. Use type: "table" or "list" option.', detectedType };
+        // Fallback: extract text content when element is not a table or list
+        const text = (el.textContent || '').trim();
+        return { type: 'text', text, tagName };
       })()
-    `,
-    returnByValue: true
-  });
+    `;
+  const extractArgs = { expression: extractExpr, returnByValue: true };
+  const contextId = pageController.getFrameContext();
+  if (contextId) extractArgs.contextId = contextId;
+  const result = await session.send('Runtime.evaluate', extractArgs);
 
   if (result.exceptionDetails) {
     throw new Error('Extract error: ' + result.exceptionDetails.text);
@@ -254,15 +257,12 @@ export async function executeAssert(pageController, elementLocator, params) {
 
     try {
       // Get the text content of the target element
-      const textResult = await pageController.session.send('Runtime.evaluate', {
-        expression: `
+      const textResult = await pageController.evaluateInFrame(`
           (function() {
             const el = document.querySelector(${JSON.stringify(selector)});
             return el ? el.textContent : null;
           })()
-        `,
-        returnByValue: true
-      });
+        `);
 
       const actualText = textResult.result.value;
       textAssertion.found = actualText !== null;

package/src/runner/execute-input.js

@@ -229,8 +229,8 @@ export async function executeFillActive(pageController, inputEmulator, params) {
   const session = pageController.session;
 
   // Parse params
-  const value = typeof params === 'string' ? params : params.value;
-  const clear = typeof params === 'object' ? params.clear !== false : true;
+  const value = typeof params === 'string' ? params : (params && params.value);
+  const clear = typeof params === 'object' && params !== null ? params.clear !== false : true;
 
   // Check if there's an active element and if it's editable
   const checkResult = await session.send('Runtime.evaluate', {