agent-web-interface 4.0.0

package/dist/src/snapshot/element-resolver.js

@@ -0,0 +1,379 @@
+/**
+ * Element Resolver
+ *
+ * Resolves node_id from snapshot to actionable element.
+ * Provides CDP-based clicking using backendNodeId for guaranteed uniqueness.
+ */
+/**
+ * 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 async function clickByBackendNodeId(cdp, backendNodeId) {
+    // 1. Scroll element into view (ensures element is visible and clickable)
+    try {
+        await cdp.send('DOM.scrollIntoViewIfNeeded', { backendNodeId });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to scroll element into view (backendNodeId: ${backendNodeId}). ` +
+            `The element may have been removed from the DOM. ` +
+            `Try capturing a fresh snapshot. Original error: ${message}`);
+    }
+    // 2. Get element bounding box to calculate click coordinates
+    let model;
+    try {
+        const result = await cdp.send('DOM.getBoxModel', { backendNodeId });
+        model = result.model;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get element bounding box (backendNodeId: ${backendNodeId}). ` +
+            `The element may be hidden or have no layout. Original error: ${message}`);
+    }
+    // Validate we have a content box to click
+    if (!model?.content || model.content.length < 8) {
+        throw new Error(`Element has no clickable area (backendNodeId: ${backendNodeId}). ` +
+            `The element may be zero-sized or not rendered.`);
+    }
+    // The content quad is an array of 8 numbers: [x1,y1, x2,y2, x3,y3, x4,y4]
+    // representing the four corners of the content box in viewport coordinates.
+    // We click at the center of the content box.
+    const [x1, y1, x2, , , y3] = model.content;
+    const centerX = x1 + (x2 - x1) / 2;
+    const centerY = y1 + (y3 - y1) / 2;
+    // Validate coordinates are reasonable (not negative or extremely large)
+    if (centerX < 0 || centerY < 0 || !Number.isFinite(centerX) || !Number.isFinite(centerY)) {
+        throw new Error(`Invalid click coordinates (x: ${centerX}, y: ${centerY}) for backendNodeId: ${backendNodeId}. ` +
+            `The element may be positioned off-screen.`);
+    }
+    // 3. Click at the element's center using CDP Input domain
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mousePressed',
+        x: centerX,
+        y: centerY,
+        button: 'left',
+        clickCount: 1,
+    });
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mouseReleased',
+        x: centerX,
+        y: centerY,
+        button: 'left',
+        clickCount: 1,
+    });
+}
+// ============================================================================
+// Modifier Bitmask Constants
+// ============================================================================
+/**
+ * CDP Input modifier bitmask values.
+ * These are ORed together for combined modifiers.
+ */
+export const MODIFIER_ALT = 1;
+export const MODIFIER_CTRL = 2;
+export const MODIFIER_META = 4;
+export const MODIFIER_SHIFT = 8;
+// ============================================================================
+// Key Code Mapping
+// ============================================================================
+/**
+ * Maps key names to their DOM key codes.
+ * Used for Input.dispatchKeyEvent CDP commands.
+ */
+const KEY_DEFINITIONS = {
+    Enter: { code: 'Enter', keyCode: 13, key: 'Enter', text: '\r' },
+    Tab: { code: 'Tab', keyCode: 9, key: 'Tab' },
+    Escape: { code: 'Escape', keyCode: 27, key: 'Escape' },
+    Backspace: { code: 'Backspace', keyCode: 8, key: 'Backspace' },
+    Delete: { code: 'Delete', keyCode: 46, key: 'Delete' },
+    Space: { code: 'Space', keyCode: 32, key: ' ', text: ' ' },
+    ArrowUp: { code: 'ArrowUp', keyCode: 38, key: 'ArrowUp' },
+    ArrowDown: { code: 'ArrowDown', keyCode: 40, key: 'ArrowDown' },
+    ArrowLeft: { code: 'ArrowLeft', keyCode: 37, key: 'ArrowLeft' },
+    ArrowRight: { code: 'ArrowRight', keyCode: 39, key: 'ArrowRight' },
+    Home: { code: 'Home', keyCode: 36, key: 'Home' },
+    End: { code: 'End', keyCode: 35, key: 'End' },
+    PageUp: { code: 'PageUp', keyCode: 33, key: 'PageUp' },
+    PageDown: { code: 'PageDown', keyCode: 34, key: 'PageDown' },
+};
+/**
+ * Convert modifier names to CDP modifier bitmask.
+ */
+function computeModifiers(modifiers) {
+    if (!modifiers)
+        return 0;
+    let bits = 0;
+    for (const mod of modifiers) {
+        switch (mod.toLowerCase()) {
+            case 'alt':
+                bits |= MODIFIER_ALT;
+                break;
+            case 'control':
+            case 'ctrl':
+                bits |= MODIFIER_CTRL;
+                break;
+            case 'meta':
+            case 'cmd':
+            case 'command':
+                bits |= MODIFIER_META;
+                break;
+            case 'shift':
+                bits |= MODIFIER_SHIFT;
+                break;
+        }
+    }
+    return bits;
+}
+// ============================================================================
+// Helper: Get Element Center Coordinates
+// ============================================================================
+/**
+ * Get the center coordinates of an element by its backendNodeId.
+ * Scrolls the element into view first.
+ */
+async function getElementCenter(cdp, backendNodeId) {
+    // Scroll into view
+    try {
+        await cdp.send('DOM.scrollIntoViewIfNeeded', { backendNodeId });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to scroll element into view (backendNodeId: ${backendNodeId}). ` +
+            `The element may have been removed from the DOM. Original error: ${message}`);
+    }
+    // Get bounding box
+    let model;
+    try {
+        const result = await cdp.send('DOM.getBoxModel', { backendNodeId });
+        model = result.model;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to get element bounding box (backendNodeId: ${backendNodeId}). ` +
+            `The element may be hidden or have no layout. Original error: ${message}`);
+    }
+    if (!model?.content || model.content.length < 8) {
+        throw new Error(`Element has no clickable area (backendNodeId: ${backendNodeId}). ` +
+            `The element may be zero-sized or not rendered.`);
+    }
+    const [x1, y1, x2, , , y3] = model.content;
+    const x = x1 + (x2 - x1) / 2;
+    const y = y1 + (y3 - y1) / 2;
+    if (x < 0 || y < 0 || !Number.isFinite(x) || !Number.isFinite(y)) {
+        throw new Error(`Invalid coordinates (x: ${x}, y: ${y}) for backendNodeId: ${backendNodeId}. ` +
+            `The element may be positioned off-screen.`);
+    }
+    return { x, y };
+}
+// ============================================================================
+// Clear Text Helper
+// ============================================================================
+/**
+ * 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 async function clearFocusedText(cdp) {
+    // Select all (Ctrl+A)
+    await cdp.send('Input.dispatchKeyEvent', {
+        type: 'keyDown',
+        key: 'a',
+        code: 'KeyA',
+        modifiers: MODIFIER_CTRL,
+        windowsVirtualKeyCode: 65,
+    });
+    await cdp.send('Input.dispatchKeyEvent', {
+        type: 'keyUp',
+        key: 'a',
+        code: 'KeyA',
+        modifiers: MODIFIER_CTRL,
+        windowsVirtualKeyCode: 65,
+    });
+    // Delete selected text
+    await cdp.send('Input.dispatchKeyEvent', {
+        type: 'keyDown',
+        key: 'Delete',
+        code: 'Delete',
+        windowsVirtualKeyCode: 46,
+    });
+    await cdp.send('Input.dispatchKeyEvent', {
+        type: 'keyUp',
+        key: 'Delete',
+        code: 'Delete',
+        windowsVirtualKeyCode: 46,
+    });
+}
+// ============================================================================
+// Type Text
+// ============================================================================
+/**
+ * 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 async function typeByBackendNodeId(cdp, backendNodeId, text, options) {
+    // 1. Focus the element by clicking it
+    await clickByBackendNodeId(cdp, backendNodeId);
+    // 2. Clear existing text if requested
+    if (options?.clear) {
+        await clearFocusedText(cdp);
+    }
+    // 3. Insert text
+    await cdp.send('Input.insertText', { text });
+}
+// ============================================================================
+// Press Key
+// ============================================================================
+/**
+ * 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 async function pressKey(cdp, key, modifiers) {
+    const keyDef = KEY_DEFINITIONS[key];
+    if (!keyDef) {
+        throw new Error(`Unknown key: "${key}". Supported keys: ${Object.keys(KEY_DEFINITIONS).join(', ')}`);
+    }
+    const modifierBits = computeModifiers(modifiers);
+    await cdp.send('Input.dispatchKeyEvent', {
+        type: 'keyDown',
+        key: keyDef.key,
+        code: keyDef.code,
+        windowsVirtualKeyCode: keyDef.keyCode,
+        modifiers: modifierBits,
+        text: keyDef.text,
+    });
+    await cdp.send('Input.dispatchKeyEvent', {
+        type: 'keyUp',
+        key: keyDef.key,
+        code: keyDef.code,
+        windowsVirtualKeyCode: keyDef.keyCode,
+        modifiers: modifierBits,
+    });
+}
+// ============================================================================
+// Select Option
+// ============================================================================
+/**
+ * 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 async function selectOption(cdp, backendNodeId, value) {
+    // Resolve the backendNodeId to a Runtime object
+    const { object } = await cdp.send('DOM.resolveNode', { backendNodeId });
+    if (!object.objectId) {
+        throw new Error(`Failed to resolve element (backendNodeId: ${backendNodeId})`);
+    }
+    // Call a function on the element to select the option
+    const result = await cdp.send('Runtime.callFunctionOn', {
+        objectId: object.objectId,
+        functionDeclaration: `function(targetValue) {
+      if (this.tagName !== 'SELECT') {
+        throw new Error('Element is not a <select> element');
+      }
+      const options = Array.from(this.options);
+      const option = options.find(o =>
+        o.value === targetValue ||
+        o.text === targetValue ||
+        o.text.trim() === targetValue
+      );
+      if (!option) {
+        const available = options.map(o => o.text || o.value).join(', ');
+        throw new Error('Option not found: "' + targetValue + '". Available: ' + available);
+      }
+      this.value = option.value;
+      this.dispatchEvent(new Event('change', { bubbles: true }));
+      return option.text;
+    }`,
+        arguments: [{ value }],
+        returnByValue: true,
+    });
+    if (result.exceptionDetails) {
+        throw new Error(`Failed to select option: ${result.exceptionDetails.exception?.description ?? 'Unknown error'}`);
+    }
+    return result.result.value;
+}
+// ============================================================================
+// Hover
+// ============================================================================
+/**
+ * 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 async function hoverByBackendNodeId(cdp, backendNodeId) {
+    const { x, y } = await getElementCenter(cdp, backendNodeId);
+    await cdp.send('Input.dispatchMouseEvent', {
+        type: 'mouseMoved',
+        x,
+        y,
+    });
+}
+// ============================================================================
+// Scroll
+// ============================================================================
+/**
+ * Scroll an element into view using CDP.
+ *
+ * @param cdp - CDP client instance
+ * @param backendNodeId - Element to scroll into view
+ */
+export async function scrollIntoView(cdp, backendNodeId) {
+    try {
+        await cdp.send('DOM.scrollIntoViewIfNeeded', { backendNodeId });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to scroll element into view (backendNodeId: ${backendNodeId}). ` +
+            `Original error: ${message}`);
+    }
+}
+/**
+ * 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 async function scrollPage(cdp, direction, amount = 500) {
+    const scrollY = direction === 'down' ? amount : -amount;
+    await cdp.send('Runtime.evaluate', {
+        expression: `window.scrollBy(0, ${scrollY})`,
+    });
+}
+//# sourceMappingURL=element-resolver.js.map

package/dist/src/snapshot/element-resolver.js.map

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

package/dist/src/snapshot/extractors/attribute-extractor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Attribute Extractor
+ *
+ * Extracts element-specific attributes for the NodeAttributes field.
+ * Handles input type, placeholder, href, src, alt, heading level,
+ * form action/method, test IDs, and explicit role attributes.
+ *
+ * @module snapshot/extractors/attribute-extractor
+ */
+import type { RawDomNode, RawAxNode } from './types.js';
+import type { NodeKind, NodeAttributes } from '../snapshot.types.js';
+/**
+ * Options for attribute extraction
+ */
+export interface AttributeExtractionOptions {
+    /** Include input values (default: false for security) */
+    includeValues?: boolean;
+    /** Redact password field values (default: true) */
+    redactSensitive?: boolean;
+    /** Remove sensitive query params from URLs (default: true) */
+    sanitizeUrls?: boolean;
+}
+/**
+ * Sanitize a URL by removing sensitive query parameters.
+ *
+ * @param url - URL to sanitize
+ * @returns Sanitized URL
+ */
+export declare function sanitizeUrl(url: string): string;
+/**
+ * Extract element-specific attributes based on NodeKind.
+ *
+ * @param domNode - Raw DOM node (can be undefined)
+ * @param kind - Semantic node kind
+ * @param options - Extraction options
+ * @param axNode - Optional AX node for additional properties
+ * @returns NodeAttributes or undefined if no attributes
+ */
+export declare function extractAttributes(domNode: RawDomNode | undefined, kind: NodeKind, options?: AttributeExtractionOptions, axNode?: RawAxNode): NodeAttributes | undefined;
+//# sourceMappingURL=attribute-extractor.d.ts.map

package/dist/src/snapshot/extractors/attribute-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute-extractor.d.ts","sourceRoot":"","sources":["../../../../src/snapshot/extractors/attribute-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,mDAAmD;IACnD,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,8DAA8D;IAC9D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAyCD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA0B/C;AA2FD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,0BAA+B,EACxC,MAAM,CAAC,EAAE,SAAS,GACjB,cAAc,GAAG,SAAS,CAgF5B"}

package/dist/src/snapshot/extractors/attribute-extractor.js

@@ -0,0 +1,237 @@
+/**
+ * Attribute Extractor
+ *
+ * Extracts element-specific attributes for the NodeAttributes field.
+ * Handles input type, placeholder, href, src, alt, heading level,
+ * form action/method, test IDs, and explicit role attributes.
+ *
+ * @module snapshot/extractors/attribute-extractor
+ */
+/**
+ * Default extraction options
+ */
+const DEFAULT_OPTIONS = {
+    includeValues: false,
+    redactSensitive: true,
+    sanitizeUrls: true,
+};
+/**
+ * Sensitive query parameter names to strip from URLs
+ */
+const SENSITIVE_PARAMS = new Set([
+    'token',
+    'key',
+    'api_key',
+    'apikey',
+    'auth',
+    'password',
+    'secret',
+    'access_token',
+    'refresh_token',
+    'session',
+    'sessionid',
+    'session_id',
+    'credential',
+    'credentials',
+]);
+/**
+ * Maximum URL length before truncation
+ */
+const MAX_URL_LENGTH = 200;
+/**
+ * Test ID attribute names in priority order
+ */
+const TEST_ID_ATTRS = ['data-testid', 'data-test', 'data-cy', 'data-test-id'];
+/**
+ * Sanitize a URL by removing sensitive query parameters.
+ *
+ * @param url - URL to sanitize
+ * @returns Sanitized URL
+ */
+export function sanitizeUrl(url) {
+    // Handle relative URLs - just truncate if needed
+    if (!url.startsWith('http://') && !url.startsWith('https://')) {
+        return truncateUrl(url);
+    }
+    try {
+        const parsed = new URL(url);
+        // Remove sensitive params
+        const paramsToDelete = [];
+        for (const key of parsed.searchParams.keys()) {
+            const lowerKey = key.toLowerCase();
+            if (SENSITIVE_PARAMS.has(lowerKey)) {
+                paramsToDelete.push(key);
+            }
+        }
+        for (const key of paramsToDelete) {
+            parsed.searchParams.delete(key);
+        }
+        return truncateUrl(parsed.toString());
+    }
+    catch {
+        // Invalid URL, return as-is (truncated)
+        return truncateUrl(url);
+    }
+}
+/**
+ * Truncate a URL if it exceeds maximum length.
+ *
+ * @param url - URL to truncate
+ * @returns Truncated URL with '...' suffix if needed
+ */
+function truncateUrl(url) {
+    if (url.length <= MAX_URL_LENGTH) {
+        return url;
+    }
+    return url.substring(0, MAX_URL_LENGTH) + '...';
+}
+/**
+ * Extract domain + path from an image src URL.
+ *
+ * @param src - Image source URL
+ * @returns Domain and path only (no query params)
+ */
+function extractImageSrc(src) {
+    // Handle data URLs
+    if (src.startsWith('data:')) {
+        return '[data-url]';
+    }
+    // Handle relative URLs
+    if (!src.startsWith('http://') && !src.startsWith('https://')) {
+        return src;
+    }
+    try {
+        const parsed = new URL(src);
+        return `${parsed.host}${parsed.pathname}`;
+    }
+    catch {
+        return src;
+    }
+}
+/**
+ * Extract heading level from tag name.
+ *
+ * @param tagName - HTML tag name (e.g., 'H1', 'H2')
+ * @returns Heading level (1-6) or undefined
+ */
+function getHeadingLevelFromTag(tagName) {
+    const match = /^H([1-6])$/.exec(tagName.toUpperCase());
+    if (match) {
+        return parseInt(match[1], 10);
+    }
+    return undefined;
+}
+/**
+ * Get heading level from AX node properties.
+ *
+ * @param axNode - Accessibility node
+ * @returns Heading level from AX properties or undefined
+ */
+function getHeadingLevelFromAx(axNode) {
+    if (!axNode?.properties) {
+        return undefined;
+    }
+    const levelProp = axNode.properties.find((p) => p.name === 'level');
+    if (levelProp?.value?.value !== undefined) {
+        const level = Number(levelProp.value.value);
+        if (level >= 1 && level <= 6) {
+            return level;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract test ID from DOM attributes.
+ *
+ * @param attrs - DOM attributes
+ * @returns Test ID or undefined
+ */
+function extractTestId(attrs) {
+    for (const attrName of TEST_ID_ATTRS) {
+        const value = attrs[attrName];
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * Extract element-specific attributes based on NodeKind.
+ *
+ * @param domNode - Raw DOM node (can be undefined)
+ * @param kind - Semantic node kind
+ * @param options - Extraction options
+ * @param axNode - Optional AX node for additional properties
+ * @returns NodeAttributes or undefined if no attributes
+ */
+export function extractAttributes(domNode, kind, options = {}, axNode) {
+    if (!domNode) {
+        return undefined;
+    }
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const attrs = {};
+    const domAttrs = domNode.attributes ?? {};
+    // Input type (for input and combobox kinds)
+    if ((kind === 'input' || kind === 'combobox') && domAttrs.type) {
+        attrs.input_type = domAttrs.type;
+    }
+    // Placeholder (any kind)
+    if (domAttrs.placeholder && domAttrs.placeholder.length > 0) {
+        attrs.placeholder = domAttrs.placeholder;
+    }
+    // Value extraction (with redaction)
+    if (opts.includeValues && domAttrs.value !== undefined) {
+        const isPassword = domAttrs.type?.toLowerCase() === 'password';
+        if (isPassword && opts.redactSensitive) {
+            attrs.value = '[REDACTED]';
+        }
+        else {
+            attrs.value = domAttrs.value;
+        }
+    }
+    // Link href (only for link kind)
+    if (kind === 'link' && domAttrs.href) {
+        attrs.href = opts.sanitizeUrls ? sanitizeUrl(domAttrs.href) : domAttrs.href;
+    }
+    // Image alt and src (only for image kind)
+    if (kind === 'image') {
+        if (domAttrs.alt) {
+            attrs.alt = domAttrs.alt;
+        }
+        if (domAttrs.src) {
+            attrs.src = extractImageSrc(domAttrs.src);
+        }
+    }
+    // Heading level (only for heading kind)
+    if (kind === 'heading') {
+        // AX tree level takes precedence (more accurate for ARIA headings)
+        const axLevel = getHeadingLevelFromAx(axNode);
+        const tagLevel = getHeadingLevelFromTag(domNode.nodeName);
+        attrs.heading_level = axLevel ?? tagLevel;
+    }
+    // Form action and method (only for form kind)
+    if (kind === 'form') {
+        if (domAttrs.action) {
+            attrs.action = domAttrs.action;
+        }
+        if (domAttrs.method) {
+            attrs.method = domAttrs.method;
+        }
+    }
+    // Autocomplete (for input/select/combobox kinds)
+    if (domAttrs.autocomplete) {
+        attrs.autocomplete = domAttrs.autocomplete;
+    }
+    // Test ID (any kind)
+    const testId = extractTestId(domAttrs);
+    if (testId) {
+        attrs.test_id = testId;
+    }
+    // Explicit role attribute (any kind)
+    if (domAttrs.role) {
+        attrs.role = domAttrs.role;
+    }
+    // Return undefined if no attributes were extracted
+    return Object.keys(attrs).length > 0 ? attrs : undefined;
+}
+//# sourceMappingURL=attribute-extractor.js.map