@dyyz1993/agent-browser 0.13.2 → 0.23.0

package/dist/snapshot-store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * SnapshotStore - In-memory store for snapshot data with stable selectors.
+ *
+ * Each snapshot gets a unique sequential ID (snap_1, snap_2, ...).
+ * Elements within each snapshot have stable CSS selectors and XPaths
+ * that can be retrieved later by snapshot_id + ref/index.
+ */
+export interface SnapshotElement {
+    /** Ref ID (e.g., "e1") */
+    ref: string;
+    /** Display index (1-based, e.g., 1, 2, 3) */
+    index: number;
+    /** ARIA role (e.g., "button", "link", "textbox") */
+    role: string;
+    /** Accessible name (e.g., "Submit") */
+    name?: string;
+    /** Stable CSS selector (e.g., "#su", "input[name='wd']") */
+    cssSelector: string;
+    /** Stable XPath (e.g., "//*[@id='su']") */
+    xpath: string;
+}
+export interface SnapshotEntry {
+    /** Unique snapshot ID (e.g., "snap_3") */
+    id: string;
+    /** Creation timestamp */
+    timestamp: number;
+    /** Page URL at snapshot time */
+    url: string;
+    /** Iframe path if snapshot was taken inside an iframe */
+    framePath?: string;
+    /** Elements keyed by ref ID (e.g., "e1" -> SnapshotElement) */
+    elements: Map<string, SnapshotElement>;
+    /** Whether stable selectors have been generated for this snapshot */
+    selectorsGenerated: boolean;
+}
+export declare class SnapshotStore {
+    private snapshots;
+    private counter;
+    /**
+     * Create a new snapshot entry.
+     * @returns The generated snapshot ID (e.g., "snap_3")
+     */
+    create(url: string, elements: SnapshotElement[], framePath?: string): string;
+    /**
+     * Get a snapshot entry by ID.
+     */
+    get(id: string): SnapshotEntry | undefined;
+    /**
+     * Get a specific element from a snapshot by ref or index.
+     *
+     * @param snapId - Snapshot ID (e.g., "snap_3")
+     * @param refOrIndex - Either a ref like "e1" or "@e1", or an index like "1"
+     * @returns The SnapshotElement or undefined
+     */
+    getElement(snapId: string, refOrIndex: string): SnapshotElement | undefined;
+    /**
+     * Get all elements from a snapshot as an array, sorted by index.
+     */
+    getElements(snapId: string): SnapshotElement[] | undefined;
+    /**
+     * Get the current counter value (for testing/debugging).
+     */
+    getCounter(): number;
+    /**
+     * Check if a snapshot exists.
+     */
+    has(id: string): boolean;
+    /**
+     * Mark selectors as generated for a snapshot.
+     */
+    markSelectorsGenerated(id: string): void;
+    /**
+     * Check if selectors have been generated for a snapshot.
+     */
+    isSelectorsGenerated(id: string): boolean;
+}
+//# sourceMappingURL=snapshot-store.d.ts.map

package/dist/snapshot-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.d.ts","sourceRoot":"","sources":["../src/snapshot-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACvC,qEAAqE;IACrE,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,OAAO,CAAa;IAE5B;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM;IAc5E;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI1C;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAuB3E;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE,GAAG,SAAS;IAM1D;;OAEG;IACH,UAAU,IAAI,MAAM;IAIpB;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;OAEG;IACH,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKxC;;OAEG;IACH,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAG1C"}

package/dist/snapshot-store.js

@@ -0,0 +1,97 @@
+/**
+ * SnapshotStore - In-memory store for snapshot data with stable selectors.
+ *
+ * Each snapshot gets a unique sequential ID (snap_1, snap_2, ...).
+ * Elements within each snapshot have stable CSS selectors and XPaths
+ * that can be retrieved later by snapshot_id + ref/index.
+ */
+export class SnapshotStore {
+    snapshots = new Map();
+    counter = 0;
+    /**
+     * Create a new snapshot entry.
+     * @returns The generated snapshot ID (e.g., "snap_3")
+     */
+    create(url, elements, framePath) {
+        const id = `snap_${++this.counter}`;
+        const elementMap = new Map(elements.map((e) => [e.ref, e]));
+        this.snapshots.set(id, {
+            id,
+            timestamp: Date.now(),
+            url,
+            framePath,
+            elements: elementMap,
+            selectorsGenerated: false,
+        });
+        return id;
+    }
+    /**
+     * Get a snapshot entry by ID.
+     */
+    get(id) {
+        return this.snapshots.get(id);
+    }
+    /**
+     * Get a specific element from a snapshot by ref or index.
+     *
+     * @param snapId - Snapshot ID (e.g., "snap_3")
+     * @param refOrIndex - Either a ref like "e1" or "@e1", or an index like "1"
+     * @returns The SnapshotElement or undefined
+     */
+    getElement(snapId, refOrIndex) {
+        const entry = this.snapshots.get(snapId);
+        if (!entry)
+            return undefined;
+        // Strip @ prefix if present (e.g., "@e1" -> "e1")
+        const cleaned = refOrIndex.startsWith('@') ? refOrIndex.slice(1) : refOrIndex;
+        // Try as ref first (e.g., "e1")
+        if (entry.elements.has(cleaned)) {
+            return entry.elements.get(cleaned);
+        }
+        // Try as index (e.g., "1")
+        const index = parseInt(cleaned, 10);
+        if (!isNaN(index)) {
+            for (const el of entry.elements.values()) {
+                if (el.index === index)
+                    return el;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Get all elements from a snapshot as an array, sorted by index.
+     */
+    getElements(snapId) {
+        const entry = this.snapshots.get(snapId);
+        if (!entry)
+            return undefined;
+        return Array.from(entry.elements.values()).sort((a, b) => a.index - b.index);
+    }
+    /**
+     * Get the current counter value (for testing/debugging).
+     */
+    getCounter() {
+        return this.counter;
+    }
+    /**
+     * Check if a snapshot exists.
+     */
+    has(id) {
+        return this.snapshots.has(id);
+    }
+    /**
+     * Mark selectors as generated for a snapshot.
+     */
+    markSelectorsGenerated(id) {
+        const entry = this.snapshots.get(id);
+        if (entry)
+            entry.selectorsGenerated = true;
+    }
+    /**
+     * Check if selectors have been generated for a snapshot.
+     */
+    isSelectorsGenerated(id) {
+        return this.snapshots.get(id)?.selectorsGenerated ?? false;
+    }
+}
+//# sourceMappingURL=snapshot-store.js.map

package/dist/snapshot-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-store.js","sourceRoot":"","sources":["../src/snapshot-store.ts"],"names":[],"mappings":"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"}

package/dist/snapshot.d.ts

@@ -37,25 +37,24 @@ export interface EnhancedSnapshot {
     refs: RefMap;
 }
 export interface SnapshotOptions {
-    /** Only include interactive elements (buttons, links, inputs, etc.) */
     interactive?: boolean;
-    /** Include cursor-interactive elements (cursor:pointer, onclick, tabindex) */
     cursor?: boolean;
-    /** Maximum depth of tree to include (0 = root only) */
     maxDepth?: number;
-    /** Remove structural elements without meaningful content */
     compact?: boolean;
-    /** CSS selector to scope the snapshot */
     selector?: string;
-    /** Include xpath and cssPath in refs (requires selector) */
     path?: boolean;
-    /** Include element attributes in refs (requires selector) */
     attrs?: boolean;
+    selectors?: boolean;
+    all?: boolean;
 }
 /**
  * Reset ref counter (call at start of each snapshot)
  */
 export declare function resetRefs(): void;
+export declare function generateStableSelectors(page: Page | Frame, refs: RefMap): Promise<Record<string, {
+    cssSelector: string;
+    xpath: string;
+}>>;
 /**
  * Get enhanced snapshot with refs and optional filtering
  */

package/dist/snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAW,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,MAAM;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,0EAA0E;QAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,uCAAuC;QACvC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,8CAA8C;QAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gDAAgD;QAChD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAKD;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAEhC;AAwTD;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,GAAG,KAAK,GAAG,YAAY,EACjC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CA+E3B;AAu0BD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX;IACD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB,CAUA;AA6BD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAYhE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAqB5E;AAkDD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAyC9E;AAyBD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS1E"}
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAW,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE1E,MAAM,WAAW,MAAM;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,0EAA0E;QAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,uCAAuC;QACvC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,8CAA8C;QAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,gDAAgD;QAChD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACrC,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAKD;;GAEG;AACH,wBAAgB,SAAS,IAAI,IAAI,CAEhC;AAwTD,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,IAAI,GAAG,KAAK,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CA4VjE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,GAAG,KAAK,GAAG,YAAY,EACjC,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAwF3B;AA44BD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAcnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX;IACD,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB,CAUA;AA6BD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAYhE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAqB5E;AAkDD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,GAAE,MAAU,GAAG,MAAM,CAyC9E;AAyBD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS1E"}

package/dist/snapshot.js

@@ -311,6 +311,369 @@ 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) {
+                    if (!element.className || typeof element.className !== 'string')
+                        return [];
+                    return element.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) {
+                    if (element.id) {
+                        const sel = '#' + CSS.escape(element.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;
+                    if (element.id)
+                        return '#' + CSS.escape(element.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 { }
+                    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) {
+                    if (element.id)
+                        return '//*[@id="' + element.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) {
+                        if (current.id) {
+                            parts.unshift('//*[@id="' + current.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 { }
+    }
+    return result;
+}
 /**
  * Get enhanced snapshot with refs and optional filtering
  */
@@ -378,7 +741,80 @@ 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) {