browser-debugger-cli/dist/commands/dom/DomElementResolver.d.ts

DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port.

/**
 * DOM element resolver for index and selector-based access.
 *
 * Provides centralized resolution of DOM elements from:
 * - Numeric indices (referencing cached query results)
 * - CSS selectors (used directly)
 *
 * Handles cache validation, staleness detection, and automatic refresh.
 * When cache is stale due to navigation, automatically re-runs the original
 * query to provide seamless "just works" experience.
 *
 * @example
 * ```typescript
 * const resolver = DomElementResolver.getInstance();
 *
 * // Resolve index from cached query
 * const target = await resolver.resolve('0');
 * // { success: true, selector: '.cached-selector', index: 1 }
 *
 * // Resolve CSS selector directly
 * const target = await resolver.resolve('button.submit');
 * // { success: true, selector: 'button.submit' }
 *
 * // Get nodeId for cached index (throws if invalid)
 * const nodeId = await resolver.getNodeIdForIndex(0);
 * ```
 */
import { QueryCacheManager } from '../../session/QueryCacheManager.js';
/**
 * Successful result of resolving a selector or index argument.
 */
export interface ElementTargetSuccess {
    /** Resolution succeeded */
    success: true;
    /** CSS selector to use */
    selector: string;
    /** 0-based index for selector (if resolved from cached query) */
    index?: number | undefined;
}
/**
 * Failed result of resolving a selector or index argument.
 */
export interface ElementTargetFailure {
    /** Resolution failed */
    success: false;
    /** Error message */
    error: string;
    /** Exit code for the error */
    exitCode: number;
    /** Suggestion for fixing the error */
    suggestion?: string | undefined;
}
/**
 * Result of resolving a selector or index argument to an element target.
 * Discriminated union that guarantees selector exists when success is true.
 */
export type ElementTargetResult = ElementTargetSuccess | ElementTargetFailure;
/**
 * Singleton resolver for DOM element access patterns.
 *
 * Centralizes element resolution with cache validation, automatic refresh,
 * and consistent error handling.
 */
export declare class DomElementResolver {
    private static instance;
    private cacheManager;
    /**
     * Create a new resolver instance.
     *
     * @param cacheManager - Query cache manager (defaults to singleton)
     */
    constructor(cacheManager?: QueryCacheManager);
    /**
     * Refresh stale cache by re-running the original query.
     *
     * Called automatically when cache validation fails due to navigation.
     * Re-queries using the stored selector and updates the cache with fresh results.
     *
     * @param selector - Original CSS selector from stale cache
     * @returns Fresh query result
     */
    private refreshCache;
    /**
     * Get the singleton instance.
     *
     * @returns DomElementResolver instance
     */
    static getInstance(): DomElementResolver;
    /**
     * Reset the singleton instance (for testing).
     */
    static resetInstance(): void;
    /**
     * Resolve a selectorOrIndex argument to an element target.
     *
     * Handles the common pattern of accepting either:
     * - A CSS selector string (used directly)
     * - A numeric index (resolved from cached query results)
     *
     * Automatically refreshes stale cache by re-running the original query.
     * This provides a "just works" experience where navigation doesn't break
     * index-based access.
     *
     * @param selectorOrIndex - CSS selector or numeric index from query results
     * @param explicitIndex - Optional explicit --index flag value (0-based)
     * @returns Resolution result with selector and optional index
     *
     * @example
     * ```typescript
     * const target = await resolver.resolve('button');
     * // { success: true, selector: 'button' }
     *
     * const target = await resolver.resolve('0');
     * // { success: true, selector: '.cached-selector', index: 1 }
     * ```
     */
    resolve(selectorOrIndex: string, explicitIndex?: number): Promise<ElementTargetResult>;
    /**
     * Get nodeId for a cached index.
     *
     * Automatically refreshes stale cache by re-running the original query.
     * Throws CommandError only if refresh fails or index is out of range after refresh.
     *
     * @param index - Zero-based index from query results
     * @returns Node with nodeId from cache
     * @throws CommandError if cache missing, index out of range after refresh, or node not found
     *
     * @example
     * ```typescript
     * const node = await resolver.getNodeIdForIndex(0);
     * console.log(node.nodeId); // CDP node ID
     * ```
     */
    getNodeIdForIndex(index: number): Promise<{
        nodeId: number;
    }>;
    /**
     * Get the count of cached elements.
     *
     * Automatically refreshes stale cache by re-running the original query.
     *
     * @returns Number of cached elements
     * @throws CommandError if cache is missing or refresh fails
     */
    getElementCount(): Promise<number>;
    /**
     * Check if the argument is a numeric index.
     *
     * @param selectorOrIndex - String to check
     * @returns True if the string is a numeric index
     */
    isNumericIndex(selectorOrIndex: string): boolean;
}
//# sourceMappingURL=DomElementResolver.d.ts.map