cdp-skill 1.0.8 → 1.0.15

package/src/aria.js

@@ -184,7 +184,8 @@ export function createQueryOutputProcessor(session) {
  * @param {Object} elementLocator - Element locator instance
  * @returns {Object} Role query executor interface
  */
-export function createRoleQueryExecutor(session, elementLocator) {
+export function createRoleQueryExecutor(session, elementLocator, options = {}) {
+  const getFrameContext = options.getFrameContext || null;
   const outputProcessor = createQueryOutputProcessor(session);
 
   async function releaseObject(objectId) {
@@ -327,10 +328,12 @@ export function createRoleQueryExecutor(session, elementLocator) {
 
     let result;
     try {
-      result = await session.send('Runtime.evaluate', {
-        expression,
-        returnByValue: false
-      });
+      const evalArgs = { expression, returnByValue: false };
+      if (getFrameContext) {
+        const contextId = getFrameContext();
+        if (contextId) evalArgs.contextId = contextId;
+      }
+      result = await session.send('Runtime.evaluate', evalArgs);
     } catch (error) {
       throw new Error(`Role query error: ${error.message}`);
     }
@@ -353,7 +356,7 @@ export function createRoleQueryExecutor(session, elementLocator) {
       throw new Error(`Role query error: ${error.message}`);
     }
 
-    const { createElementHandle } = await import('./dom.js');
+    const { createElementHandle } = await import('./dom/element-handle.js');
     const elements = props.result
       .filter(p => /^\d+$/.test(p.name) && p.value && p.value.objectId)
       .map(p => createElementHandle(session, p.value.objectId, {
@@ -472,7 +475,7 @@ export function createRoleQueryExecutor(session, elementLocator) {
 // The snapshot script runs entirely in the browser context
 const SNAPSHOT_SCRIPT = `
 (function generateAriaSnapshot(rootSelector, options) {
-  const { mode = 'ai', maxDepth = 50, maxElements = 0, includeText = false, includeFrames = false, viewportOnly = false, pierceShadow = false, preserveRefs = false, since = null, internal = false } = options || {};
+  const { mode = 'ai', maxDepth = 50, maxElements = 0, includeText = false, includeFrames = false, viewportOnly = false, pierceShadow = false, preserveRefs = false, since = null, internal = false, frameIdentifier = 'f0' } = options || {};
 
   // Viewport dimensions for viewport-only mode
   const viewportWidth = window.innerWidth;
@@ -488,6 +491,9 @@ const SNAPSHOT_SCRIPT = `
     window.__ariaSnapshotId = 0;
   }
 
+  // Store frame identifier for ref generation (used by all ref-generating operations)
+  window.__ariaFrameIdentifier = frameIdentifier;
+
   // Compute page hash for change detection
   // Hash combines: URL + scroll position + DOM size + interactive element count
   function computePageHash() {
@@ -511,7 +517,7 @@ const SNAPSHOT_SCRIPT = `
     if (currentHash === window.__ariaSnapshotHash) {
       return {
         unchanged: true,
-        snapshotId: 's' + window.__ariaSnapshotId,
+        snapshotId: frameIdentifier + 's' + window.__ariaSnapshotId,
         hash: currentHash
       };
     }
@@ -740,10 +746,18 @@ const SNAPSHOT_SCRIPT = `
 
     // Text content for buttons, links, etc.
     const role = getAriaRole(el);
-    if (['button', 'link', 'menuitem', 'option', 'tab', 'treeitem', 'heading'].includes(role)) {
+    if (['button', 'link', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option',
+         'tab', 'treeitem', 'heading', 'gridcell', 'listitem', 'columnheader',
+         'rowheader', 'cell', 'switch'].includes(role)) {
       return normalizeWhitespace(el.textContent);
     }
 
+    // Short-text fallback for any remaining role with empty name
+    if (role) {
+      const fallbackText = normalizeWhitespace(el.textContent);
+      if (fallbackText && fallbackText.length <= 80) return fallbackText;
+    }
+
     return '';
   }
 
@@ -918,6 +932,14 @@ const SNAPSHOT_SCRIPT = `
     // Check if element already has a ref in current snapshot
     if (elementRefs.has(el)) return elementRefs.get(el);
 
+    // Build metadata with shadow host path for shadow DOM elements
+    function buildMeta(element, r, n) {
+      const meta = { selector: generateSelector(element), role: r || '', name: n || '' };
+      const shadowPath = getShadowHostPath(element);
+      if (shadowPath.length > 0) meta.shadowHostPath = shadowPath;
+      return meta;
+    }
+
     // Check if element already has a ref from a previous snapshot
     // This ensures the same element always gets the same ref
     if (window.__ariaRefs) {
@@ -926,19 +948,19 @@ const SNAPSHOT_SCRIPT = `
           elementRefs.set(el, existingRef);
           refElements.set(existingRef, el);
           // Update metadata in case it changed
-          refMeta.set(existingRef, { selector: generateSelector(el), role: role || '', name: name || '' });
+          refMeta.set(existingRef, buildMeta(el, role, name));
           return existingRef;
         }
       }
     }
 
-    // New element - assign new ref with versioned format: s{snapshotId}e{refCounter}
+    // New element - assign new ref with versioned format: f{frameId}s{snapshotId}e{refCounter}
     refCounter++;
-    const ref = 's' + currentSnapshotId + 'e' + refCounter;
+    const ref = frameIdentifier + 's' + currentSnapshotId + 'e' + refCounter;
     elementRefs.set(el, ref);
     refElements.set(ref, el);
     // Store metadata for re-resolution fallback
-    refMeta.set(ref, { selector: generateSelector(el), role: role || '', name: name || '' });
+    refMeta.set(ref, buildMeta(el, role, name));
     return ref;
   }
 
@@ -1220,10 +1242,21 @@ const SNAPSHOT_SCRIPT = `
     return document.querySelector(selector);
   }
 
-  // Main execution
-  const root = resolveRoot(rootSelector);
+  // Main execution - auto-scope to <main> when no root specified (reduces footer/boilerplate noise)
+  let autoScoped = false;
+  let root;
+  if (!rootSelector) {
+    const mainEl = document.querySelector('main, [role="main"]');
+    if (mainEl) {
+      root = mainEl;
+      autoScoped = true;
+    } else {
+      root = document.body;
+    }
+  } else {
+    root = resolveRoot(rootSelector);
+  }
   if (!root) {
-    // Provide helpful error message based on selector type
     const roleMatch = rootSelector && rootSelector.match(/^role=(.+)$/i);
     if (roleMatch) {
       return { error: 'Root element not found for role: ' + roleMatch[1] + '. Use CSS selector (e.g., "main", "#container") or check that an element with this role exists.' };
@@ -1242,22 +1275,39 @@ const SNAPSHOT_SCRIPT = `
     refs[ref] = generateSelector(el);
   }
 
-  function generateSelector(el) {
+  // Build the shadow host path for an element (empty array if not in shadow DOM)
+  function getShadowHostPath(el) {
+    const hosts = [];
+    let node = el;
+    while (node) {
+      const root = node.getRootNode();
+      if (root instanceof ShadowRoot) {
+        hosts.unshift(generateSelectorForElement(root.host));
+        node = root.host;
+      } else {
+        break;
+      }
+    }
+    return hosts;
+  }
+
+  // Generate a CSS selector for a single element (used by both generateSelector and shadow path)
+  function generateSelectorForElement(el) {
     if (el.id) return '#' + CSS.escape(el.id);
 
-    // Try unique attributes
     for (const attr of ['data-testid', 'data-test-id', 'data-cy', 'name']) {
       if (el.hasAttribute(attr)) {
         const value = el.getAttribute(attr);
         const selector = '[' + attr + '=' + JSON.stringify(value) + ']';
-        if (document.querySelectorAll(selector).length === 1) return selector;
+        try { if (document.querySelectorAll(selector).length === 1) return selector; } catch(e) {}
       }
     }
 
-    // Build path
+    // Build path from element up to its root (document or shadow root)
     const path = [];
     let current = el;
-    while (current && current !== document.body) {
+    const rootNode = el.getRootNode();
+    while (current && current !== document.body && current !== rootNode) {
       let selector = current.tagName.toLowerCase();
       if (current.id) {
         selector = '#' + CSS.escape(current.id);
@@ -1279,7 +1329,38 @@ const SNAPSHOT_SCRIPT = `
     return path.join(' > ');
   }
 
-  const yaml = tree.children ? tree.children.map(c => renderYaml(c, '')).join('\\n') : renderYaml(tree, '');
+  function generateSelector(el) {
+    return generateSelectorForElement(el);
+  }
+
+  // Build landmark header when auto-scoped to main (shows what else is on the page)
+  let landmarkHeader = '';
+  if (autoScoped) {
+    const LM_QUERIES = [
+      { sel: 'nav, [role="navigation"]', role: 'navigation' },
+      { sel: 'header, [role="banner"]', role: 'banner' },
+      { sel: 'footer, [role="contentinfo"]', role: 'contentinfo' },
+      { sel: 'aside, [role="complementary"]', role: 'complementary' },
+      { sel: '[role="search"]', role: 'search' }
+    ];
+    const found = [];
+    for (const { sel, role } of LM_QUERIES) {
+      try {
+        const count = document.querySelectorAll(sel).length;
+        if (count > 0) {
+          const label = document.querySelector(sel).getAttribute('aria-label');
+          found.push(label ? role + ' "' + label + '"' : role);
+        }
+      } catch (e) {}
+    }
+    if (found.length > 0) {
+      landmarkHeader = '# Auto-scoped to main content. Other landmarks: ' + found.join(', ') + '\\n# Use {root: "body"} for full page\\n';
+    } else {
+      landmarkHeader = '# Auto-scoped to main content. Use {root: "body"} for full page\\n';
+    }
+  }
+
+  const yaml = landmarkHeader + (tree.children ? tree.children.map(c => renderYaml(c, '')).join('\\n') : renderYaml(tree, ''));
 
   // Store refs globally for later use (e.g., click by ref)
   // When preserveRefs is true, merge new refs into existing map instead of overwriting
@@ -1306,13 +1387,15 @@ const SNAPSHOT_SCRIPT = `
   // Store page hash for change detection
   window.__ariaSnapshotHash = computePageHash();
 
-  return {
+  const snapshotResult = {
     tree,
     yaml,
     refs,
     truncated: limitReached,
-    snapshotId: 's' + currentSnapshotId
+    snapshotId: frameIdentifier + 's' + currentSnapshotId
   };
+  if (autoScoped) snapshotResult.autoScoped = true;
+  return snapshotResult;
 })
 `;
 
@@ -1321,7 +1404,9 @@ const SNAPSHOT_SCRIPT = `
  * @param {Object} session - CDP session
  * @returns {Object} ARIA snapshot interface
  */
-export function createAriaSnapshot(session) {
+export function createAriaSnapshot(session, options = {}) {
+  const getFrameContext = options.getFrameContext || null;
+  const getFrameIdentifier = options.getFrameIdentifier || null;
   /**
    * Generate accessibility snapshot of the page
    * @param {Object} options - Snapshot options
@@ -1335,17 +1420,25 @@ export function createAriaSnapshot(session) {
    * @param {boolean} options.viewportOnly - Only include elements visible in viewport (default: false)
    * @param {boolean} options.pierceShadow - Traverse into open shadow DOM trees (default: false)
    * @param {boolean} options.preserveRefs - Merge new refs into existing instead of overwriting (default: false)
-   * @param {string} options.since - Snapshot ID to check against (e.g., "s1") - returns {unchanged: true} if page hasn't changed
+   * @param {string} options.since - Snapshot ID to check against (e.g., "f0s1") - returns {unchanged: true} if page hasn't changed
    * @returns {Promise<Object>} Snapshot result with tree, yaml, refs, and snapshotId
    */
   async function generate(options = {}) {
     const { root = null, mode = 'ai', detail = 'full', maxDepth = 50, maxElements = 0, includeText = false, includeFrames = false, viewportOnly = false, pierceShadow = false, preserveRefs = false, since = null, internal = false } = options;
 
-    const result = await session.send('Runtime.evaluate', {
-      expression: `(${SNAPSHOT_SCRIPT})(${JSON.stringify(root)}, ${JSON.stringify({ mode, detail, maxDepth, maxElements, includeText, includeFrames, viewportOnly, pierceShadow, preserveRefs, since, internal })})`,
+    // Get frame identifier for ref generation (f0 for main frame, f1, f2, etc. for iframes)
+    const frameIdentifier = getFrameIdentifier ? await getFrameIdentifier() : 'f0';
+
+    const evalArgs = {
+      expression: `(${SNAPSHOT_SCRIPT})(${JSON.stringify(root)}, ${JSON.stringify({ mode, detail, maxDepth, maxElements, includeText, includeFrames, viewportOnly, pierceShadow, preserveRefs, since, internal, frameIdentifier })})`,
       returnByValue: true,
       awaitPromise: false
-    });
+    };
+    if (getFrameContext) {
+      const contextId = getFrameContext();
+      if (contextId) evalArgs.contextId = contextId;
+    }
+    const result = await session.send('Runtime.evaluate', evalArgs);
 
     if (result.exceptionDetails) {
       throw new Error(`Snapshot generation failed: ${result.exceptionDetails.text}`);
@@ -1405,7 +1498,9 @@ export function createAriaSnapshot(session) {
         interactiveElements++;
       }
 
-      if (node.box) {
+      // Count all semantic (non-generic, non-staticText) nodes as viewport elements
+      // since they passed isVisible() checks during tree construction
+      if (role && role !== 'generic' && role !== 'staticText') {
         viewportElements++;
       }
 
@@ -1554,7 +1649,7 @@ export function createAriaSnapshot(session) {
    * @returns {Promise<Object>} Element info with selector, box, and connection status
    */
   async function getElementByRef(ref) {
-    const result = await session.send('Runtime.evaluate', {
+    const evalArgs = {
       expression: `(function() {
         const ref = ${JSON.stringify(ref)};
         const refsMap = window.__ariaRefs;
@@ -1619,32 +1714,133 @@ export function createAriaSnapshot(session) {
           return buildResult(el, false);
         }
 
+        // Helper to check if candidate matches role+name
+        function matchesRoleAndName(candidate, meta) {
+          if (!candidate || !candidate.isConnected) return false;
+          const candidateRole = getRole(candidate);
+          const roleMatch = !meta.role || candidateRole === meta.role;
+          if (!roleMatch) return false;
+          if (!meta.name) return true;
+          const candidateName = getAccessibleName(candidate);
+          return candidateName.toLowerCase().includes(meta.name.toLowerCase().substring(0, 100));
+        }
+
+        // Helper to resolve a CSS selector through a chain of shadow hosts
+        function queryShadow(shadowHostPath, selector) {
+          let root = document;
+          for (const hostSel of shadowHostPath) {
+            try {
+              const host = root.querySelector(hostSel);
+              if (!host || !host.shadowRoot) return null;
+              root = host.shadowRoot;
+            } catch (e) { return null; }
+          }
+          try { return root.querySelector(selector); } catch (e) { return null; }
+        }
+
+        // Helper to querySelectorAll through shadow hosts
+        function queryShadowAll(shadowHostPath, selector) {
+          let root = document;
+          for (const hostSel of shadowHostPath) {
+            try {
+              const host = root.querySelector(hostSel);
+              if (!host || !host.shadowRoot) return [];
+              root = host.shadowRoot;
+            } catch (e) { return []; }
+          }
+          try { return Array.from(root.querySelectorAll(selector)); } catch (e) { return []; }
+        }
+
+        // Helper to collect all shadow roots in the document for broad search
+        function collectShadowRoots(node, roots) {
+          if (node.shadowRoot) {
+            roots.push(node.shadowRoot);
+            collectShadowRoots(node.shadowRoot, roots);
+          }
+          const children = node.children || node.childNodes || [];
+          for (const child of children) {
+            if (child.nodeType === 1) collectShadowRoots(child, roots);
+          }
+          return roots;
+        }
+
         // 2. Element is null or stale - attempt re-resolution via metadata
         if (metaMap) {
           const meta = metaMap.get(ref);
-          if (meta && meta.selector) {
-            try {
-              const candidate = document.querySelector(meta.selector);
-              if (candidate && candidate.isConnected) {
-                // Verify role matches
-                const candidateRole = getRole(candidate);
-                const roleMatch = !meta.role || candidateRole === meta.role;
-
-                // Verify name matches (loose: contains check, case-insensitive)
-                let nameMatch = true;
-                if (meta.name) {
-                  const candidateName = getAccessibleName(candidate);
-                  nameMatch = candidateName.toLowerCase().includes(meta.name.toLowerCase().substring(0, 100));
-                }
+          if (meta) {
+            const hasShadowPath = meta.shadowHostPath && meta.shadowHostPath.length > 0;
 
-                if (roleMatch && nameMatch) {
-                  // Update the refs map so subsequent lookups are fast
+            // 2a. Try stored CSS selector first (fastest)
+            if (meta.selector) {
+              try {
+                const candidate = hasShadowPath
+                  ? queryShadow(meta.shadowHostPath, meta.selector)
+                  : document.querySelector(meta.selector);
+                if (matchesRoleAndName(candidate, meta)) {
                   if (refsMap) refsMap.set(ref, candidate);
                   return buildResult(candidate, true);
                 }
+              } catch (e) {
+                // querySelector can throw on invalid selectors - fall through
+              }
+            }
+
+            // 2b. Broader search: find by role + name
+            if (meta.role) {
+              const roleSelectors = {
+                'link': 'a[href]',
+                'button': 'button,[role="button"]',
+                'heading': 'h1,h2,h3,h4,h5,h6,[role="heading"]',
+                'textbox': 'input:not([type]),input[type="text"],input[type="email"],input[type="url"],input[type="search"],input[type="tel"],textarea,[role="textbox"]',
+                'checkbox': 'input[type="checkbox"],[role="checkbox"]',
+                'radio': 'input[type="radio"],[role="radio"]',
+                'combobox': 'select,[role="combobox"],[role="listbox"]',
+                'img': 'img,[role="img"]',
+                'listitem': 'li,[role="listitem"]',
+                'tab': '[role="tab"]',
+                'menuitem': '[role="menuitem"]'
+              };
+              const sel = roleSelectors[meta.role] || '[role="' + meta.role + '"]';
+
+              // Search in known shadow path first, then light DOM
+              if (hasShadowPath) {
+                try {
+                  const candidates = queryShadowAll(meta.shadowHostPath, sel);
+                  for (const candidate of candidates) {
+                    if (matchesRoleAndName(candidate, meta)) {
+                      if (refsMap) refsMap.set(ref, candidate);
+                      return buildResult(candidate, true);
+                    }
+                  }
+                } catch (e) {}
+              }
+
+              // Light DOM search
+              try {
+                const candidates = document.querySelectorAll(sel);
+                for (const candidate of candidates) {
+                  if (matchesRoleAndName(candidate, meta)) {
+                    if (refsMap) refsMap.set(ref, candidate);
+                    return buildResult(candidate, true);
+                  }
+                }
+              } catch (e) {}
+
+              // 2c. Last resort: search ALL shadow roots in the document
+              if (!hasShadowPath) {
+                try {
+                  const shadowRoots = collectShadowRoots(document.body, []);
+                  for (const sr of shadowRoots) {
+                    const candidates = sr.querySelectorAll(sel);
+                    for (const candidate of candidates) {
+                      if (matchesRoleAndName(candidate, meta)) {
+                        if (refsMap) refsMap.set(ref, candidate);
+                        return buildResult(candidate, true);
+                      }
+                    }
+                  }
+                } catch (e) {}
               }
-            } catch (e) {
-              // querySelector can throw on invalid selectors - fall through
             }
           }
         }
@@ -1656,7 +1852,12 @@ export function createAriaSnapshot(session) {
         return null;
       })()`,
       returnByValue: true
-    });
+    };
+    if (getFrameContext) {
+      const contextId = getFrameContext();
+      if (contextId) evalArgs.contextId = contextId;
+    }
+    const result = await session.send('Runtime.evaluate', evalArgs);
 
     return result.result.value;
   }

package/src/cdp/browser.js

@@ -196,6 +196,8 @@ export async function launchChrome(options = {}) {
 
   if (headless) {
     args.push('--headless=new');
+    args.push('--disable-dev-shm-usage');
+    args.push('--disable-software-rasterizer');
   }
 
   // Chrome requires --user-data-dir for remote debugging (as of Chrome 129+)
@@ -218,10 +220,13 @@ export async function launchChrome(options = {}) {
     stdio: ['ignore', 'ignore', 'pipe'] // capture stderr
   });
 
-  // Collect stderr output for error reporting
+  // Collect stderr output for error reporting (capped at 50KB)
+  const MAX_STDERR_BYTES = 50 * 1024;
   let stderrOutput = '';
   chromeProcess.stderr.on('data', (data) => {
-    stderrOutput += data.toString();
+    if (stderrOutput.length < MAX_STDERR_BYTES) {
+      stderrOutput += data.toString().substring(0, MAX_STDERR_BYTES - stderrOutput.length);
+    }
   });
 
   // Don't let this process keep Node alive
@@ -418,6 +423,11 @@ export function createBrowser(options = {}) {
     while (targetLocks.has(targetId)) {
       await targetLocks.get(targetId);
     }
+    // Atomic check-and-set: verify lock is still free after await
+    if (targetLocks.has(targetId)) {
+      // Another acquirer won the race, recursively retry
+      return acquireLock(targetId);
+    }
     // Create a new lock
     let releaseFn;
     const lockPromise = new Promise(resolve => {
@@ -440,9 +450,15 @@ export function createBrowser(options = {}) {
     }
   }
 
-  async function doConnect() {
+  async function doConnect(abortSignal) {
     const version = await discovery.getVersion();
     connection = createConnection(version.webSocketDebuggerUrl);
+
+    // Check if aborted before connecting
+    if (abortSignal?.aborted) {
+      throw new Error('Connection aborted');
+    }
+
     await connection.connect();
 
     targetManager = createTargetManager(connection);
@@ -459,9 +475,11 @@ export function createBrowser(options = {}) {
   async function connect() {
     if (connected) return;
 
-    const connectPromise = doConnect();
+    const controller = new AbortController();
+    const connectPromise = doConnect(controller.signal);
     const timeoutPromise = new Promise((_, reject) => {
       setTimeout(() => {
+        controller.abort();
         reject(timeoutError(`Connection to Chrome timed out after ${connectTimeout}ms`));
       }, connectTimeout);
     });