/**
 * Centralized element-resolution layer.
 *
 * Browser actions used to each duplicate the same pattern: look the ref up
 * in the in-memory map, fall back to a CSS selector, generate similar
 * "ref not found" error messages, etc. As stale-ref auto-recovery and
 * selector normalization grew, that duplication started to drift.
 *
 * This module owns:
 *  - selector normalization (delegated to ./selectors)
 *  - aria-ref lookup with stale-ref auto-recovery via captured metadata
 *  - role + name + text (Playwright getByRole / getByText) entry points
 *
 * Actions never call `page.locator(selector).first()` or `page.locator(\`aria-ref=${ref}\`)`
 * directly anymore — they go through `resolveLocator` (or the lower-level
 * helpers it exports for backward compat).
 */
import type { Locator, Page } from "playwright-core";
import { type ElementRef } from "./snapshot.js";
export interface LocatorInput {
    ref?: string;
    selector?: string;
    role?: string;
    name?: string;
    /** Visible text match (Playwright getByText). */
    text?: string;
}
export interface ResolveOptions {
    /** Display label used in error messages ("element", "start element", etc.). */
    label?: string;
    /** Whether the action is destructive (gates fuzzy-name recovery). */
    destructive?: boolean;
    /** Name of the CSS-alternative parameter, or null when the action has none. */
    selectorParam?: "selector" | "element" | null;
}
export interface ResolveOk {
    ok: true;
    locator: Locator;
    label: string;
    /** Ref that ultimately produced the locator (may differ from input on recovery). */
    refUsed?: string;
    /** Stable selector that ultimately produced the locator, when known. */
    selectorUsed?: string;
    /** Recovery path used, when applicable. */
    recoveredVia?: "stableSelector" | "roleExactName" | "roleFuzzyName";
}
export interface ResolveFail {
    ok: false;
    message: string;
}
export type ResolveResult = ResolveOk | ResolveFail;
/**
 * "Destructive" = a click that submits/posts/sends/deletes, where landing
 * on the wrong button would do real damage. Recovery for these is restricted
 * to high-confidence paths (stableSelector + role+exact-name); fuzzy name
 * matches are refused so we never auto-click a "Post" lookalike.
 */
export declare function looksDestructive(meta: ElementRef): boolean;
/**
 * Top-level resolver. Handles all four input shapes and unifies error
 * formatting. Most action methods call this with only one of {ref, selector}
 * set; role/name/text are exposed for callers that want Playwright's native
 * accessibility-tree matching without a snapshot first.
 */
export declare function resolveLocator(page: Page, input: LocatorInput, opts?: ResolveOptions): Promise<ResolveResult>;
export declare function resolveSelector(page: Page, raw: unknown, paramName?: string): {
    ok: true;
    locator: Locator;
    selector: string;
    note?: string;
} | {
    ok: false;
    error: string;
};
export declare function refNotFoundMessage(ref: string, label?: string, selectorParam?: "selector" | "element" | null): string;
/**
 * Resolve a ref to a Locator, with one bounded auto-recovery pass when the
 * underlying DOM node is stale. Recovery order:
 *   1. stableSelector (data-testid / unique id / unique [name|aria-label|placeholder])
 *   2. role + exact accessible name (re-snapshotted)
 *   3. role + fuzzy accessible name (skipped for destructive actions)
 *
 * Recovery only fires when there's exactly one high-confidence candidate.
 * Ambiguous matches return the candidate list so the LLM can disambiguate.
 */
export declare function locateRefWithRecovery(page: Page, ref: string, opts?: ResolveOptions & {
    allowRecovery?: boolean;
}): Promise<ResolveResult>;
