/**
 * Selector normalization & preflight validation.
 *
 * Production logs showed three recurring selector failures:
 *   1. Over-escaped quotes from JSON tool calls — e.g. a[href=\\\"/User\\\"].
 *   2. Empty / whitespace-only strings.
 *   3. Unmatched brackets/quotes that crash the CSS parser.
 *
 * This module catches those before they reach Playwright, so the LLM gets
 * an actionable repair candidate instead of a generic locator timeout.
 *
 * It is purposely conservative: only obviously-broken selectors are repaired
 * or rejected. A selector that looks weird but parses cleanly is left alone —
 * the truth is in `document.querySelector`.
 */
export interface NormalizeResult {
    /** True if the selector is safe to pass to page.locator(). */
    ok: boolean;
    /** The cleaned selector. Only meaningful when ok=true. */
    selector: string;
    /** The original, before normalization. */
    original: string;
    /** Human-readable repair note when normalization changed something. */
    note?: string;
    /** Reason the selector was rejected when ok=false. */
    error?: string;
}
export declare function normalizeSelector(raw: unknown): NormalizeResult;
/**
 * Returns true if the selector is too broad to be safely auto-resolved for a
 * destructive action. The caller still gets to override (e.g. when the user
 * explicitly passes such a selector), but stale-ref auto-recovery and
 * fuzzy-match paths should refuse to use these.
 */
export declare function isSelectorBroad(selector: string): boolean;
/**
 * Build a Playwright-safe attribute selector. Used when emitting stable
 * selector hints from snapshot enrichment so we never produce malformed
 * attribute literals from values that contain quotes.
 */
export declare function attrSelector(attr: string, value: string): string;
