import type { Page } from "playwright-core";
/**
 * Stable element metadata captured during the post-snapshot enrichment pass.
 * The Playwright AI snapshot only gives us role/name/ref; this struct carries
 * the DOM-level facts we need for selector picking, editable detection, and
 * stale-ref recovery without re-querying the page on every action.
 */
export interface ElementRef {
    ref: string;
    role: string;
    name: string;
    /** Lower-case tag, e.g. "input", "div", "a". */
    tag?: string;
    /**
     * Best-effort stable CSS selector for this element, picked in priority:
     * data-testid → unique id → unique [name] → unique [aria-label] →
     * unique [placeholder]. Undefined if none qualify as unique on the page.
     */
    stableSelector?: string;
    /** True if input/textarea/[contenteditable]/aria-textbox-with-editable-host. */
    editable?: boolean;
    /** Current value for input/textarea (truncated). */
    value?: string;
    /** href for anchors. */
    href?: string;
    /**
     * If this element has a `data-testid` but the testid is NOT unique on the
     * page (typical of repeated feed/list action buttons),
     * we record the global count instead of emitting a stable selector. The
     * annotation surfaces this so the LLM doesn't blindly trust the testid.
     */
    testidSelectorCount?: number;
    /** Raw attributes, useful for stale-ref recovery candidate scoring. */
    attrs?: {
        testid?: string;
        id?: string;
        name?: string;
        ariaLabel?: string;
        placeholder?: string;
        type?: string;
    };
}
interface SnapshotResult {
    text: string;
    elementRefs: Map<string, ElementRef>;
}
export type SnapshotMode = "full" | "interactive" | "outline" | "efficient";
/**
 * "ai" produces Playwright's compact AI snapshot (default — best for LLM
 * summarization). "aria" produces the verbose accessibility tree output —
 * not currently used by the agent itself but exposed so external tooling
 * can request it.
 */
export type SnapshotFormat = "ai" | "aria";
/**
 * "aria" refs are the existing eN style — short and good for the *next*
 * action. "role" refs are role+name handles that the resolver re-resolves
 * on each use; safer across rerenders but only act-safe when unique.
 */
export type RefStyle = "aria" | "role";
export interface SnapshotOptions {
    mode?: SnapshotMode;
    /** CSS selector to scope snapshot to a subtree. */
    selector?: string;
    /** Strip consecutive blank lines and trailing whitespace. */
    compact?: boolean;
    /** Max nesting depth (by 2-space indentation). */
    depth?: number;
    /** Override the default char cap. */
    maxChars?: number;
    /**
     * Enable post-snapshot DOM enrichment (stable selectors + editable hints).
     * Default true. Disable for cheap snapshots where the cost of N parallel
     * evaluates per ref is not worth it.
     */
    enrich?: boolean;
    /** Output format. Default "ai". */
    snapshotFormat?: SnapshotFormat;
    /**
     * Ref style appended to interactive lines. Default "aria" (Playwright's
     * eN format). With "role", we additionally annotate each line with a
     * role+name handle: `[role-ref="button|Post"]`. The resolver supports
     * both — pass either as `ref` to actions like click/type.
     */
    refs?: RefStyle;
}
/**
 * Wipe all ref metadata. Called when the page identity changes
 * (navigation, tab switch, page close) — both the live and historical
 * caches refer to a page we no longer have.
 */
export declare function resetRefs(): void;
export declare function getElementRef(ref: string): ElementRef | undefined;
/**
 * Look up a ref's metadata in the previous-snapshot cache only. Used by
 * stale-ref recovery to locate the role/name/stableSelector of a ref the
 * LLM is acting on AFTER taking a fresh snapshot that invalidated it.
 *
 * The recovery code will NOT use this metadata to re-query via aria-ref —
 * that would point at the wrong DOM. It uses the stable attributes
 * (data-testid, etc.) and role+name pair to find the equivalent element
 * in the current snapshot.
 */
export declare function getPreviousElementRef(ref: string): ElementRef | undefined;
export declare function getAllRefs(): Map<string, ElementRef>;
export declare const FULL_DEFAULT_MAX_CHARS = 10000;
export declare const FULL_HARD_MAX_CHARS = 16000;
export declare const WIDE_FULL_HARD_MAX_CHARS = 10000;
export declare const INTERACTIVE_DEFAULT_MAX_CHARS = 8000;
export declare const INTERACTIVE_HARD_MAX_CHARS = 12000;
export declare const EFFICIENT_MAX_CHARS = 8000;
export declare const EFFICIENT_MAX_DEPTH = 6;
export declare function resolveSnapshotLimit(opts: SnapshotOptions, mode: SnapshotMode): {
    limit: number;
    notice?: string;
};
export declare function formatCappedSnapshotText(body: string, opts: {
    limit: number;
    notice?: string;
    prefix?: string;
    truncatedHint?: string;
    preserveTail?: boolean;
}): string;
/**
 * Take a snapshot of the page accessibility tree.
 *
 * Accepts either a SnapshotMode string (backward compat) or SnapshotOptions object.
 */
export declare function takeSnapshot(page: Page, modeOrOptions?: SnapshotMode | SnapshotOptions, maxCharsOverride?: number): Promise<SnapshotResult>;
/**
 * Parse element refs from snapshot text into the currentRefs map.
 *
 * Three passes, richest first. Each pass uses `currentRefs.has` as a
 * "don't overwrite" guard so a later, looser pattern can never replace
 * a name we already captured.
 *
 * Pass C (role-only) exists because Playwright's ai-mode emits refs on
 * structural nodes that have no accessible name — `- generic [ref=e1]:`,
 * `- link [ref=e5]:` when a site wraps several visual elements in a single
 * link with empty aria-name. Without this pass those refs appear in
 * the snapshot text the LLM reads but never enter currentRefs, so any
 * action against them returns "ref not found or stale" *before*
 * stale-ref recovery has any metadata to work with. Exported so unit
 * tests can drive it directly without spinning up a browser.
 */
export declare function parseRefs(snapshot: string): void;
export {};
