agent-web-interface 4.0.0

package/dist/src/shared/services/selector-builder.service.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Selector Builder Service
+ *
+ * Generates CSS, XPath, and accessibility selectors for DOM elements
+ */
+import type { CdpClient } from '../../cdp/cdp-client.interface.js';
+import type { Selectors } from '../types/index.js';
+export declare class SelectorBuilderService {
+    private readonly cdpClient;
+    constructor(cdpClient: CdpClient);
+    /**
+     * Build comprehensive selectors for a given node
+     */
+    buildSelectors(nodeId: number, _frameId: string): Promise<Selectors>;
+    /**
+     * Build a CSS selector for an element
+     * Strategy: Use ID if available, otherwise build a path using classes/nth-child
+     */
+    private buildCssSelector;
+    /**
+     * Build a CSS path using tag names and nth-child
+     */
+    private buildCssPath;
+    /**
+     * Build an XPath selector for an element
+     */
+    private buildXPathSelector;
+    /**
+     * Build an accessibility selector (role-based)
+     */
+    private buildAccessibilitySelector;
+    /**
+     * Get node description from CDP
+     */
+    private getNodeDescription;
+    /**
+     * Get parent node ID
+     */
+    private getParentNode;
+    /**
+     * Get the nth-child position of a node among its siblings
+     */
+    private getNthChildPosition;
+    /**
+     * Check if a CSS selector uniquely identifies a single element
+     */
+    private isSelectorUnique;
+    /**
+     * Parse CDP attributes array to key-value pairs
+     */
+    private parseAttributes;
+}
+//# sourceMappingURL=selector-builder.service.d.ts.map

package/dist/src/shared/services/selector-builder.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector-builder.service.d.ts","sourceRoot":"","sources":["../../../../src/shared/services/selector-builder.service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAWnD,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAAT,SAAS,EAAE,SAAS;IAEjD;;OAEG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAU1E;;;OAGG;YACW,gBAAgB;IA8B9B;;OAEG;YACW,YAAY;IAmC1B;;OAEG;YACW,kBAAkB;IAsChC;;OAEG;YACW,0BAA0B;IAyBxC;;OAEG;YACW,kBAAkB;IAMhC;;OAEG;YACW,aAAa;IAmC3B;;OAEG;YACW,mBAAmB;IAiCjC;;OAEG;YACW,gBAAgB;IAe9B;;OAEG;IACH,OAAO,CAAC,eAAe;CAOxB"}

package/dist/src/shared/services/selector-builder.service.js

@@ -0,0 +1,240 @@
+/**
+ * Selector Builder Service
+ *
+ * Generates CSS, XPath, and accessibility selectors for DOM elements
+ */
+export class SelectorBuilderService {
+    cdpClient;
+    constructor(cdpClient) {
+        this.cdpClient = cdpClient;
+    }
+    /**
+     * Build comprehensive selectors for a given node
+     */
+    async buildSelectors(nodeId, _frameId) {
+        const [css, xpath, ax] = await Promise.all([
+            this.buildCssSelector(nodeId),
+            this.buildXPathSelector(nodeId),
+            this.buildAccessibilitySelector(nodeId),
+        ]);
+        return { css, xpath, ax };
+    }
+    /**
+     * Build a CSS selector for an element
+     * Strategy: Use ID if available, otherwise build a path using classes/nth-child
+     */
+    async buildCssSelector(nodeId) {
+        try {
+            const nodeInfo = await this.getNodeDescription(nodeId);
+            const attributes = this.parseAttributes(nodeInfo.node.attributes ?? []);
+            // Strategy 1: Use ID (most specific)
+            if (attributes.id) {
+                return `#${attributes.id}`;
+            }
+            // Strategy 2: Use unique class combination
+            if (attributes.class) {
+                const classes = attributes.class.split(/\s+/).filter(Boolean);
+                if (classes.length > 0) {
+                    const classSelector = `.${classes.join('.')}`;
+                    const isUnique = await this.isSelectorUnique(classSelector);
+                    if (isUnique) {
+                        return classSelector;
+                    }
+                }
+            }
+            // Strategy 3: Build a path using tag names and nth-child
+            const path = await this.buildCssPath(nodeId);
+            return path;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Build a CSS path using tag names and nth-child
+     */
+    async buildCssPath(nodeId) {
+        const segments = [];
+        let currentNodeId = nodeId;
+        try {
+            while (currentNodeId) {
+                const nodeInfo = await this.getNodeDescription(currentNodeId);
+                const tagName = nodeInfo.node.localName.toLowerCase();
+                // Get the nth-child position
+                const position = await this.getNthChildPosition(currentNodeId);
+                if (tagName === 'html') {
+                    segments.unshift('html');
+                    break;
+                }
+                if (position > 1) {
+                    segments.unshift(`${tagName}:nth-child(${position})`);
+                }
+                else {
+                    segments.unshift(tagName);
+                }
+                // Get parent node
+                const parent = await this.getParentNode(currentNodeId);
+                if (!parent)
+                    break;
+                currentNodeId = parent;
+            }
+            return segments.join(' > ');
+        }
+        catch {
+            return 'body';
+        }
+    }
+    /**
+     * Build an XPath selector for an element
+     */
+    async buildXPathSelector(nodeId) {
+        try {
+            const segments = [];
+            let currentNodeId = nodeId;
+            while (currentNodeId) {
+                const nodeInfo = await this.getNodeDescription(currentNodeId);
+                const tagName = nodeInfo.node.localName.toLowerCase();
+                const attributes = this.parseAttributes(nodeInfo.node.attributes ?? []);
+                // Use ID if available
+                if (attributes.id) {
+                    segments.unshift(`//*[@id="${attributes.id}"]`);
+                    break;
+                }
+                // Get position among siblings
+                const position = await this.getNthChildPosition(currentNodeId);
+                if (tagName === 'html') {
+                    segments.unshift('/html');
+                    break;
+                }
+                segments.unshift(`/${tagName}[${position}]`);
+                // Get parent node
+                const parent = await this.getParentNode(currentNodeId);
+                if (!parent)
+                    break;
+                currentNodeId = parent;
+            }
+            return segments.join('');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Build an accessibility selector (role-based)
+     */
+    async buildAccessibilitySelector(nodeId) {
+        try {
+            const nodeInfo = await this.getNodeDescription(nodeId);
+            const attributes = this.parseAttributes(nodeInfo.node.attributes ?? []);
+            const role = attributes.role ?? attributes['aria-role'];
+            const label = attributes['aria-label'];
+            const name = attributes.name;
+            if (role && label) {
+                return `role=${role}[label="${label}"]`;
+            }
+            if (role && name) {
+                return `role=${role}[name="${name}"]`;
+            }
+            if (role) {
+                return `role=${role}`;
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Get node description from CDP
+     */
+    async getNodeDescription(nodeId) {
+        return this.cdpClient.send('DOM.describeNode', {
+            nodeId,
+        });
+    }
+    /**
+     * Get parent node ID
+     */
+    async getParentNode(nodeId) {
+        try {
+            const resolved = await this.cdpClient.send('DOM.resolveNode', { nodeId });
+            const objectId = resolved.object?.objectId;
+            if (!objectId) {
+                return null;
+            }
+            const parentResult = await this.cdpClient.send('Runtime.callFunctionOn', {
+                objectId,
+                functionDeclaration: 'function() { return this.parentElement; }',
+                returnByValue: false,
+            });
+            const parentObjectId = parentResult.result.objectId;
+            if (!parentObjectId) {
+                return null;
+            }
+            const parentNode = await this.cdpClient.send('DOM.describeNode', {
+                objectId: parentObjectId,
+            });
+            return parentNode.node.nodeId;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get the nth-child position of a node among its siblings
+     */
+    async getNthChildPosition(nodeId) {
+        try {
+            const resolved = await this.cdpClient.send('DOM.resolveNode', { nodeId });
+            const objectId = resolved.object?.objectId;
+            if (!objectId)
+                return 1;
+            const result = await this.cdpClient.send('Runtime.callFunctionOn', {
+                objectId,
+                functionDeclaration: `
+          function() {
+            if (!this.parentElement) {
+              return 1;
+            }
+            const siblings = Array.from(this.parentElement.children).filter(
+              (child) => child.tagName === this.tagName
+            );
+            const index = siblings.indexOf(this);
+            return index === -1 ? 1 : index + 1;
+          }
+        `,
+                returnByValue: true,
+            });
+            return result.result.value ?? 1;
+        }
+        catch {
+            return 1;
+        }
+    }
+    /**
+     * Check if a CSS selector uniquely identifies a single element
+     */
+    async isSelectorUnique(selector) {
+        try {
+            const result = await this.cdpClient.send('Runtime.evaluate', {
+                expression: `document.querySelectorAll(${JSON.stringify(selector)}).length`,
+                returnByValue: true,
+            });
+            return result.result.value === 1;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Parse CDP attributes array to key-value pairs
+     */
+    parseAttributes(attrs) {
+        const result = {};
+        for (let i = 0; i < attrs.length; i += 2) {
+            result[attrs[i]] = attrs[i + 1];
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=selector-builder.service.js.map

package/dist/src/shared/services/selector-builder.service.js.map

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

package/dist/src/shared/types/base.types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared base types
+ *
+ * Minimal types kept for the new semantic snapshot system.
+ * New types for BaseSnapshot, ReadableNode, etc. will be added here.
+ */
+/**
+ * Bounding box for element geometry
+ */
+export interface BBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Network request/response event
+ */
+export interface NetworkEvent {
+    requestId: string;
+    url: string;
+    method: string;
+    status?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Selector types for element location
+ */
+export interface Selectors {
+    ax?: string;
+    css?: string;
+    xpath?: string;
+}
+/**
+ * DOM tree node representation (used by dom-transformer service)
+ */
+export interface DomTreeNode {
+    id: string;
+    nodeId?: number;
+    tag: string;
+    attrs?: string[];
+    text?: string;
+    children?: DomTreeNode[];
+}
+//# sourceMappingURL=base.types.d.ts.map

package/dist/src/shared/types/base.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.types.d.ts","sourceRoot":"","sources":["../../../../src/shared/types/base.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B"}

package/dist/src/shared/types/base.types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared base types
+ *
+ * Minimal types kept for the new semantic snapshot system.
+ * New types for BaseSnapshot, ReadableNode, etc. will be added here.
+ */
+export {};
+//# sourceMappingURL=base.types.js.map

package/dist/src/shared/types/base.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.types.js","sourceRoot":"","sources":["../../../../src/shared/types/base.types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/src/shared/types/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared types re-exports
+ */
+export * from './base.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/shared/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/shared/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/src/shared/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types re-exports
+ */
+export * from './base.types.js';
+//# sourceMappingURL=index.js.map

package/dist/src/shared/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/shared/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/src/snapshot/element-resolver.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Element Resolver
+ *
+ * Resolves node_id from snapshot to actionable element.
+ * Provides CDP-based clicking using backendNodeId for guaranteed uniqueness.
+ */
+import type { CdpClient } from '../cdp/cdp-client.interface.js';
+/**
+ * Click an element using CDP's backendNodeId directly.
+ *
+ * This bypasses Playwright's locator system to avoid strict mode violations
+ * when multiple elements match the same selector. The backendNodeId is
+ * guaranteed unique per DOM element within a CDP session.
+ *
+ * @param cdp - CDP client instance
+ * @param backendNodeId - CDP backend node ID (stable within session)
+ * @throws Error if element not found, not visible, or click fails
+ *
+ * @example
+ * ```typescript
+ * // Click using the unique backendNodeId from snapshot
+ * await clickByBackendNodeId(cdp, node.backend_node_id);
+ * ```
+ */
+export declare function clickByBackendNodeId(cdp: CdpClient, backendNodeId: number): Promise<void>;
+/**
+ * CDP Input modifier bitmask values.
+ * These are ORed together for combined modifiers.
+ */
+export declare const MODIFIER_ALT = 1;
+export declare const MODIFIER_CTRL = 2;
+export declare const MODIFIER_META = 4;
+export declare const MODIFIER_SHIFT = 8;
+/**
+ * Clear text in the currently focused element using Ctrl+A then Delete.
+ *
+ * This helper is used by typeByBackendNodeId and can be used directly
+ * when typing into an already-focused element.
+ *
+ * @param cdp - CDP client instance
+ */
+export declare function clearFocusedText(cdp: CdpClient): Promise<void>;
+/**
+ * Type text into an element using CDP.
+ *
+ * Focuses the element first (via click), optionally clears existing text,
+ * then inserts the new text.
+ *
+ * @param cdp - CDP client instance
+ * @param backendNodeId - Element to type into
+ * @param text - Text to type
+ * @param options.clear - If true, clears existing text first (Ctrl+A, Delete)
+ */
+export declare function typeByBackendNodeId(cdp: CdpClient, backendNodeId: number, text: string, options?: {
+    clear?: boolean;
+}): Promise<void>;
+/**
+ * Press a keyboard key using CDP.
+ *
+ * Sends keyDown and keyUp events for the specified key.
+ *
+ * @param cdp - CDP client instance
+ * @param key - Key name (e.g., 'Enter', 'Tab', 'Escape', 'ArrowDown')
+ * @param modifiers - Optional modifier keys ['Control', 'Shift', 'Alt', 'Meta']
+ */
+export declare function pressKey(cdp: CdpClient, key: string, modifiers?: string[]): Promise<void>;
+/**
+ * Select an option from a <select> element.
+ *
+ * Uses Runtime.callFunctionOn to set the select value and dispatch a change event.
+ *
+ * @param cdp - CDP client instance
+ * @param backendNodeId - The <select> element's backendNodeId
+ * @param value - Option value or visible text to select
+ * @returns The selected option's visible text
+ */
+export declare function selectOption(cdp: CdpClient, backendNodeId: number, value: string): Promise<string>;
+/**
+ * Hover over an element using CDP.
+ *
+ * Scrolls the element into view and moves the mouse to its center.
+ *
+ * @param cdp - CDP client instance
+ * @param backendNodeId - Element to hover over
+ */
+export declare function hoverByBackendNodeId(cdp: CdpClient, backendNodeId: number): Promise<void>;
+/**
+ * Scroll an element into view using CDP.
+ *
+ * @param cdp - CDP client instance
+ * @param backendNodeId - Element to scroll into view
+ */
+export declare function scrollIntoView(cdp: CdpClient, backendNodeId: number): Promise<void>;
+/**
+ * Scroll the page by a specified amount.
+ *
+ * @param cdp - CDP client instance
+ * @param direction - 'up' or 'down'
+ * @param amount - Pixels to scroll (default: 500)
+ */
+export declare function scrollPage(cdp: CdpClient, direction: 'up' | 'down', amount?: number): Promise<void>;
+//# sourceMappingURL=element-resolver.d.ts.map

package/dist/src/snapshot/element-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-resolver.d.ts","sourceRoot":"","sources":["../../../src/snapshot/element-resolver.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAEhE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiE/F;AAMD;;;GAGG;AACH,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,cAAc,IAAI,CAAC;AAuHhC;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BpE;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,SAAS,EACd,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,OAAO,CAAC,IAAI,CAAC,CAWf;AAMD;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B/F;AAMD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,SAAS,EACd,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAwCjB;AAMD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ/F;AAMD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUzF;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,IAAI,GAAG,MAAM,EACxB,MAAM,SAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAMf"}