@dyyz1993/agent-browser 0.13.2 → 0.24.0

package/dist/snapshot.js

@@ -311,6 +311,381 @@ async function suggestSelectors(page) {
     }
     return selectors;
 }
+export async function generateStableSelectors(page, refs) {
+    const result = {};
+    for (const [ref, data] of Object.entries(refs)) {
+        if (data.role === 'clickable' || data.role === 'focusable') {
+            if (data.selector && !data.selector.startsWith('getByRole')) {
+                result[ref] = { cssSelector: data.selector, xpath: '' };
+            }
+            continue;
+        }
+        try {
+            let locator;
+            if (data.name) {
+                locator = page.getByRole(data.role, {
+                    name: data.name,
+                    exact: true,
+                });
+            }
+            else {
+                locator = page.getByRole(data.role);
+            }
+            if (data.nth !== undefined) {
+                locator = locator.nth(data.nth);
+            }
+            const elementCount = await locator.count();
+            if (elementCount === 0)
+                continue;
+            const selectorData = await locator
+                .evaluate((el) => {
+                const UTILITY_CLASS_PATTERNS = [
+                    /^_/,
+                    /^css-/,
+                    /^[a-z]{1,2}$/,
+                    /^(active|disabled|hidden|visible|selected|hover|focus|current|open|closed)$/i,
+                    /^(text-|font-|bg-|p-|m-|w-|h-|flex|grid|border|rounded|shadow|opacity|z-)/,
+                    /^(sm:|md:|lg:|xl:|2xl:)/,
+                ];
+                const SEMANTIC_ATTRS = [
+                    'data-testid',
+                    'data-test',
+                    'data-cy',
+                    'name',
+                    'aria-label',
+                    'aria-labelledby',
+                    'role',
+                    'type',
+                    'placeholder',
+                    'title',
+                    'alt',
+                ];
+                function isHighEntropyClassName(className) {
+                    if (!className || className.length < 4 || className.length > 15)
+                        return false;
+                    if (/^[a-zA-Z]+_[a-zA-Z]+_{2}[a-zA-Z0-9]+$/.test(className))
+                        return true;
+                    if (/^sc-[a-zA-Z0-9]+$/.test(className))
+                        return true;
+                    const hasUpper = /[A-Z]/.test(className);
+                    const hasLower = /[a-z]/.test(className);
+                    const hasDigit = /[0-9]/.test(className);
+                    const hasSeparator = /[-_]/.test(className);
+                    if (hasSeparator)
+                        return false;
+                    if (hasUpper && hasLower && hasDigit)
+                        return true;
+                    if (/^[A-Z][a-z0-9]+[A-Z]/.test(className) && className.length <= 12)
+                        return true;
+                    if (/^[a-z]/.test(className) && /[a-z][A-Z][a-z][A-Z]/.test(className))
+                        return true;
+                    return false;
+                }
+                function isUniqueSelector(selector) {
+                    try {
+                        return document.querySelectorAll(selector).length === 1;
+                    }
+                    catch {
+                        return false;
+                    }
+                }
+                function filterUsefulClasses(element) {
+                    const htmlEl = element;
+                    if (!htmlEl.className || typeof htmlEl.className !== 'string')
+                        return [];
+                    return htmlEl.className
+                        .trim()
+                        .split(/\s+/)
+                        .filter((c) => {
+                        if (!c)
+                            return false;
+                        if (UTILITY_CLASS_PATTERNS.some((p) => p.test(c)))
+                            return false;
+                        if (isHighEntropyClassName(c))
+                            return false;
+                        return true;
+                    });
+                }
+                function tryIdSelector(element) {
+                    const htmlEl = element;
+                    if (htmlEl.id) {
+                        const sel = '#' + CSS.escape(htmlEl.id);
+                        if (isUniqueSelector(sel))
+                            return sel;
+                    }
+                    return null;
+                }
+                function getMultiAttributeSelector(element) {
+                    const tag = element.tagName.toLowerCase();
+                    const attrs = [];
+                    for (const attr of SEMANTIC_ATTRS) {
+                        const value = element.getAttribute(attr);
+                        if (value)
+                            attrs.push({ attr, value });
+                    }
+                    if (attrs.length === 0)
+                        return null;
+                    for (const { attr, value } of attrs) {
+                        const sel = tag + '[' + attr + '="' + CSS.escape(value) + '"]';
+                        if (isUniqueSelector(sel))
+                            return sel;
+                    }
+                    if (attrs.length >= 2) {
+                        for (let i = 0; i < attrs.length; i++) {
+                            for (let j = i + 1; j < attrs.length; j++) {
+                                const sel = tag +
+                                    '[' +
+                                    attrs[i].attr +
+                                    '="' +
+                                    CSS.escape(attrs[i].value) +
+                                    '"]' +
+                                    '[' +
+                                    attrs[j].attr +
+                                    '="' +
+                                    CSS.escape(attrs[j].value) +
+                                    '"]';
+                                if (isUniqueSelector(sel))
+                                    return sel;
+                            }
+                        }
+                    }
+                    return null;
+                }
+                function getAttributeClassComboSelector(element) {
+                    const tag = element.tagName.toLowerCase();
+                    const classes = filterUsefulClasses(element);
+                    if (classes.length === 0)
+                        return null;
+                    classes.sort((a, b) => b.length - a.length);
+                    const bestClass = classes[0];
+                    for (const attr of SEMANTIC_ATTRS) {
+                        const value = element.getAttribute(attr);
+                        if (value) {
+                            const sel = tag + '.' + CSS.escape(bestClass) + '[' + attr + '="' + CSS.escape(value) + '"]';
+                            if (isUniqueSelector(sel))
+                                return sel;
+                        }
+                    }
+                    return null;
+                }
+                function getBestClassSelector(element) {
+                    const classes = filterUsefulClasses(element);
+                    if (classes.length === 0)
+                        return null;
+                    classes.sort((a, b) => b.length - a.length);
+                    const tag = element.tagName.toLowerCase();
+                    for (const cls of classes) {
+                        const sel = tag + '.' + CSS.escape(cls);
+                        if (isUniqueSelector(sel))
+                            return sel;
+                    }
+                    for (let i = 2; i <= Math.min(3, classes.length); i++) {
+                        const sel = tag +
+                            '.' +
+                            classes
+                                .slice(0, i)
+                                .map((c) => CSS.escape(c))
+                                .join('.');
+                        if (isUniqueSelector(sel))
+                            return sel;
+                    }
+                    return null;
+                }
+                function getFeatureSelector(element) {
+                    if (!element || element === document.body)
+                        return null;
+                    const htmlEl = element;
+                    if (htmlEl.id)
+                        return '#' + CSS.escape(htmlEl.id);
+                    for (const attr of ['data-testid', 'data-test', 'name', 'role', 'aria-label']) {
+                        const value = element.getAttribute(attr);
+                        if (value)
+                            return element.tagName.toLowerCase() + '[' + attr + '="' + CSS.escape(value) + '"]';
+                    }
+                    const classes = filterUsefulClasses(element);
+                    if (classes.length > 0) {
+                        classes.sort((a, b) => b.length - a.length);
+                        const sel = element.tagName.toLowerCase() + '.' + CSS.escape(classes[0]);
+                        if (isUniqueSelector(sel))
+                            return sel;
+                    }
+                    return null;
+                }
+                function getBaseSelector(element) {
+                    let sel = element.tagName.toLowerCase();
+                    const classes = filterUsefulClasses(element);
+                    if (classes.length > 0) {
+                        classes.sort((a, b) => b.length - a.length);
+                        sel +=
+                            '.' +
+                                classes
+                                    .slice(0, 2)
+                                    .map((c) => CSS.escape(c))
+                                    .join('.');
+                    }
+                    return sel;
+                }
+                function makeUniqueWithNth(element, baseSelector) {
+                    const parent = element.parentElement;
+                    if (!parent)
+                        return baseSelector;
+                    const siblings = Array.from(parent.children);
+                    const sameTagSiblings = siblings.filter((s) => s.tagName === element.tagName);
+                    if (sameTagSiblings.length === 1)
+                        return baseSelector;
+                    const index = siblings.indexOf(element) + 1;
+                    return baseSelector + ':nth-child(' + index + ')';
+                }
+                function getSiblingBasedSelector(element) {
+                    let prevSibling = element.previousElementSibling;
+                    let attempts = 0;
+                    while (prevSibling && attempts < 3) {
+                        const siblingSelector = getFeatureSelector(prevSibling);
+                        if (siblingSelector && isUniqueSelector(siblingSelector)) {
+                            const elementSelector = getBaseSelector(element);
+                            const combined = siblingSelector + ' + ' + elementSelector;
+                            if (isUniqueSelector(combined))
+                                return combined;
+                        }
+                        prevSibling = prevSibling.previousElementSibling;
+                        attempts++;
+                    }
+                    return null;
+                }
+                function buildComposedSelector(element) {
+                    const selfSelector = getBestClassSelector(element);
+                    if (selfSelector && isUniqueSelector(selfSelector))
+                        return selfSelector;
+                    const parts = [];
+                    let current = element;
+                    let depth = 0;
+                    const maxDepth = 3;
+                    while (current && current !== document.body && depth < maxDepth) {
+                        const featureSelector = getFeatureSelector(current);
+                        if (featureSelector) {
+                            parts.unshift(featureSelector);
+                            const elementSelector = depth === 0 ? getBaseSelector(element) : getBaseSelector(current);
+                            const fullSelector = parts.join(' > ') + (depth > 0 ? '' : ' > ' + elementSelector);
+                            if (isUniqueSelector(fullSelector))
+                                return fullSelector;
+                        }
+                        else {
+                            const baseSelector = getBaseSelector(current);
+                            const selector = makeUniqueWithNth(current, baseSelector);
+                            parts.unshift(selector);
+                            const fullSelector = parts.join(' > ');
+                            if (isUniqueSelector(fullSelector))
+                                return fullSelector;
+                        }
+                        current = current.parentElement;
+                        depth++;
+                    }
+                    return parts.length > 0 ? parts.join(' > ') : null;
+                }
+                function tryNthChild(element) {
+                    const baseSelector = getBaseSelector(element);
+                    const uniqueSelector = makeUniqueWithNth(element, baseSelector);
+                    try {
+                        if (document.querySelectorAll(uniqueSelector).length === 1)
+                            return uniqueSelector;
+                    }
+                    catch (_e) {
+                        // Intentionally ignored: invalid CSS selector in tryNthChild
+                    }
+                    return null;
+                }
+                function buildUniquePath(element) {
+                    const parts = [];
+                    let current = element;
+                    let depth = 0;
+                    while (current && current !== document.body && depth < 5) {
+                        const baseSelector = getBaseSelector(current);
+                        const selector = makeUniqueWithNth(current, baseSelector);
+                        parts.unshift(selector);
+                        const fullSelector = parts.join(' > ');
+                        if (isUniqueSelector(fullSelector))
+                            return fullSelector;
+                        current = current.parentElement;
+                        depth++;
+                    }
+                    return parts.length > 0 ? parts.join(' > ') : null;
+                }
+                function generateXPath(element) {
+                    const htmlEl = element;
+                    if (htmlEl.id)
+                        return '//*[@id="' + htmlEl.id + '"]';
+                    const testId = element.getAttribute('data-testid');
+                    if (testId)
+                        return '//*[@data-testid="' + testId + '"]';
+                    const nameAttr = element.getAttribute('name');
+                    if (nameAttr)
+                        return '//' + element.tagName.toLowerCase() + '[@name="' + nameAttr + '"]';
+                    const parts = [];
+                    let current = element;
+                    let depth = 0;
+                    while (current && depth < 5) {
+                        const curHtml = current;
+                        if (curHtml.id) {
+                            parts.unshift('//*[@id="' + curHtml.id + '"]');
+                            break;
+                        }
+                        const testId = current.getAttribute('data-testid');
+                        if (testId) {
+                            parts.unshift('//*[@data-testid="' + testId + '"]');
+                            break;
+                        }
+                        const tagName = current.tagName.toLowerCase();
+                        const parent = current.parentElement;
+                        if (parent) {
+                            const siblings = Array.from(parent.children).filter((c) => c.tagName === current.tagName);
+                            const index = siblings.indexOf(current) + 1;
+                            parts.unshift(tagName + '[' + index + ']');
+                        }
+                        else {
+                            parts.unshift(tagName);
+                        }
+                        current = current.parentElement;
+                        depth++;
+                    }
+                    if (parts.length > 0 && !parts[0].startsWith('//'))
+                        parts.unshift('//');
+                    return parts.join('/');
+                }
+                let cssSelector = null;
+                cssSelector = tryIdSelector(el);
+                if (!cssSelector)
+                    cssSelector = getMultiAttributeSelector(el);
+                if (!cssSelector)
+                    cssSelector = getAttributeClassComboSelector(el);
+                if (!cssSelector)
+                    cssSelector = getBestClassSelector(el);
+                if (!cssSelector)
+                    cssSelector = getSiblingBasedSelector(el);
+                if (!cssSelector)
+                    cssSelector = buildComposedSelector(el);
+                if (!cssSelector)
+                    cssSelector = tryNthChild(el);
+                if (!cssSelector)
+                    cssSelector = buildUniquePath(el);
+                if (!cssSelector)
+                    cssSelector = el.tagName.toLowerCase();
+                const xpath = generateXPath(el);
+                return { cssSelector, xpath };
+            })
+                .catch(() => null);
+            if (selectorData) {
+                result[ref] = {
+                    cssSelector: selectorData.cssSelector,
+                    xpath: selectorData.xpath,
+                };
+            }
+        }
+        catch (_e) {
+            // Intentionally ignored: element ref generation failed for this element
+        }
+    }
+    return result;
+}
 /**
  * Get enhanced snapshot with refs and optional filtering
  */
@@ -378,7 +753,83 @@ export async function getEnhancedSnapshot(page, options = {}) {
     if (options.path || options.attrs) {
         await enrichRefsWithPathsAndAttrs(page, refs, options);
     }
-    return { tree: enhancedTree, refs };
+    let finalTree = enhancedTree;
+    if (options.selectors && Object.keys(refs).length > 0) {
+        const selectorMap = await buildCompactSelectors(page, refs, options);
+        if (selectorMap) {
+            finalTree += '\n## Selectors\n' + selectorMap;
+        }
+    }
+    return { tree: finalTree, refs };
+}
+async function buildCompactSelectors(page, refs, options) {
+    const entries = Object.entries(refs);
+    const parts = [];
+    const includeAll = options?.all ?? false;
+    for (const [ref, data] of entries) {
+        if (data.role === 'clickable' || data.role === 'focusable')
+            continue;
+        try {
+            let locator;
+            if (data.name) {
+                locator = page.getByRole(data.role, {
+                    name: data.name,
+                    exact: true,
+                });
+            }
+            else {
+                locator = page.getByRole(data.role);
+            }
+            if (data.nth !== undefined)
+                locator = locator.nth(data.nth);
+            if (!includeAll) {
+                const isReallyVisible = await locator
+                    .evaluate((el) => {
+                    const style = getComputedStyle(el);
+                    const rect = el.getBoundingClientRect();
+                    return !(style.display === 'none' ||
+                        style.visibility === 'hidden' ||
+                        parseFloat(style.opacity) === 0 ||
+                        (rect.width === 0 && rect.height === 0) ||
+                        rect.x + rect.width < 0 ||
+                        rect.y + rect.height < 0);
+                })
+                    .catch(() => false);
+                if (!isReallyVisible)
+                    continue;
+            }
+            const attrs = await locator
+                .evaluate((el) => {
+                const htmlEl = el;
+                const r = {};
+                if (htmlEl.dataset.testid)
+                    r['testid'] = `[data-testid="${htmlEl.dataset.testid}"]`;
+                if (htmlEl.id && !htmlEl.id.match(/^[:]/))
+                    r['id'] = '#' + CSS.escape(htmlEl.id);
+                const nameAttr = htmlEl.getAttribute('name');
+                if (nameAttr)
+                    r['name'] = `${htmlEl.tagName.toLowerCase()}[name="${nameAttr}"]`;
+                return r;
+            })
+                .catch(() => null);
+            if (!attrs)
+                continue;
+            let bestSelector = '';
+            if (attrs.testid)
+                bestSelector = attrs.testid;
+            else if (attrs.id)
+                bestSelector = attrs.id;
+            else if (attrs.name)
+                bestSelector = attrs.name;
+            if (bestSelector) {
+                parts.push(`${ref}: ${bestSelector}`);
+            }
+        }
+        catch {
+            // skip
+        }
+    }
+    return parts.join(' | ');
 }
 async function enrichRefsWithPathsAndAttrs(page, refs, options) {
     if (Object.keys(refs).length === 0) {
@@ -663,9 +1114,10 @@ async function enrichRefsWithPathsAndAttrs(page, refs, options) {
     const injectScript = `
     window.__AGENT_BROWSER_REFS__ = ${JSON.stringify(refs)};
   `;
-    await page.evaluate(injectScript);
+    if ('evaluate' in page) {
+        await page.evaluate(injectScript);
+    }
     // Evaluate the function in the browser context
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const elementData = await page.evaluate(() => {
         const STYLE_CLASS_PATTERNS = [
             /^(flex|grid|block|inline|hidden)$/,
@@ -692,7 +1144,6 @@ async function enrichRefsWithPathsAndAttrs(page, refs, options) {
             'aside',
             'form',
         ]);
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         function getSemanticClass(element) {
             const className = element.getAttribute('class');
             if (!className)
@@ -705,7 +1156,6 @@ async function enrichRefsWithPathsAndAttrs(page, refs, options) {
             const selectedClasses = classes.slice(0, 2);
             return selectedClasses.map((cls) => 'contains(@class, "' + cls + '")').join(' and ');
         }
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         function getElementIndex(element) {
             const parent = element.parentElement;
             if (!parent)
@@ -870,7 +1320,6 @@ async function enrichRefsWithPathsAndAttrs(page, refs, options) {
             return null;
         }
         const results = {};
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const refEntries = Object.entries(window.__AGENT_BROWSER_REFS__ || {});
         for (const [ref, data] of refEntries) {
             const targetRole = data.role;
@@ -941,13 +1390,14 @@ async function enrichRefsWithPathsAndAttrs(page, refs, options) {
         return;
     }
     for (const [ref, data] of Object.entries(elementData)) {
+        const typedData = data;
         if (refs[ref] && data) {
             if (options.path) {
-                refs[ref].xpath = data.xpath;
-                refs[ref].cssPath = data.cssPath;
+                refs[ref].xpath = typedData.xpath;
+                refs[ref].cssPath = typedData.cssPath;
             }
             if (options.attrs) {
-                refs[ref].attributes = data.attributes;
+                refs[ref].attributes = typedData.attributes;
             }
         }
     }
@@ -1232,8 +1682,9 @@ export function getSemanticClass(element) {
     return selectedClasses.map((cls) => `contains(@class, "${cls}")`).join(' and ');
 }
 export function generateXPath(element, maxDepth = 5) {
-    if (element.id) {
-        return `//*[@id="${element.id}"]`;
+    const elemId = element.id;
+    if (elemId) {
+        return `//*[@id="${elemId}"]`;
     }
     const testId = element.getAttribute('data-testid');
     if (testId) {
@@ -1254,8 +1705,9 @@ function buildRelativeXPath(element, maxDepth) {
     let current = element;
     let depth = 0;
     while (current && depth < maxDepth) {
-        if (current.id) {
-            path.unshift(`//*[@id="${current.id}"]`);
+        const currentId = current.id;
+        if (currentId) {
+            path.unshift(`//*[@id="${currentId}"]`);
             break;
         }
         const testId = current.getAttribute('data-testid');
@@ -1287,8 +1739,9 @@ function getElementIndex(element) {
     return siblings.indexOf(element) + 1;
 }
 export function generateCSSPath(element, maxDepth = 5) {
-    if (element.id) {
-        return `#${element.id}`;
+    const elemId = element.id;
+    if (elemId) {
+        return `#${elemId}`;
     }
     const testId = element.getAttribute('data-testid');
     if (testId) {
@@ -1298,8 +1751,9 @@ export function generateCSSPath(element, maxDepth = 5) {
     let current = element;
     let depth = 0;
     while (current && depth < maxDepth) {
-        if (current.id) {
-            path.unshift(`#${current.id}`);
+        const currentId = current.id;
+        if (currentId) {
+            path.unshift(`#${currentId}`);
             break;
         }
         const testId = current.getAttribute('data-testid');