/**
 * High-level DOM inspection helpers, exposed as act-kinds so the LLM can
 * extract page data without writing free-form JavaScript.
 *
 * Why these exist: production logs showed 7 cases of `evaluate` syntax
 * errors — the model wrote ad-hoc DOM-walking JavaScript, mistyped a
 * comma or paren, and burned a tool round-trip. Each helper here covers
 * a recurring extraction pattern with no JS surface for the LLM to misuse.
 *
 * Output shape conventions:
 *  - Return strings (cap-applied, JSON or human-readable).
 *  - When the helper finds elements, include each item's stable selector
 *    if one exists, so the LLM can chain into click/type/hover.
 */
import type { Page } from "playwright-core";
export interface ExtractVisibleTextArgs {
    selector?: string;
    /** Bounded char cap (default 8000). */
    maxChars?: number;
}
export declare function extractVisibleText(page: Page, args?: ExtractVisibleTextArgs): Promise<string>;
export interface QueryByTextArgs {
    text: string;
    /** When true, match substring case-insensitively. Default false (exact). */
    fuzzy?: boolean;
    /** Cap how many results to return. Default 20. */
    limit?: number;
}
export declare function queryByText(page: Page, args: QueryByTextArgs): Promise<string>;
export interface FindClickableNearTextArgs {
    text: string;
    /** Max ancestor levels to search. Default 5. */
    maxAncestors?: number;
    /** Cap candidate count. Default 10. */
    limit?: number;
}
export declare function findClickableNearText(page: Page, args: FindClickableNearTextArgs): Promise<string>;
export interface ExtractLinksArgs {
    selector?: string;
    /** Cap link count. Default 50. */
    limit?: number;
}
export declare function extractLinks(page: Page, args?: ExtractLinksArgs): Promise<string>;
/**
 * Site-specific social post extraction used by the built-in x skill and
 * retained for backward compatibility. Walks visible post cells and pulls
 * author handle, display name, post text, timestamp, status URL, and stable
 * selectors for action buttons when present.
 *
 * Optional `limit` caps how many cells to read; default is the first 20.
 */
export interface ExtractTweetCardsArgs {
    limit?: number;
}
export declare function extractTweetCards(page: Page, args?: ExtractTweetCardsArgs): Promise<string>;
/**
 * Quick syntactic sanity check for `evaluate` scripts. We compile via
 * `new Function` which throws on parse error without ever executing the
 * code. Catches the most common LLM syntax slips (missing parens, stray
 * commas, illegal identifiers) before a round-trip to the page.
 */
export declare function wrapEvaluateScript(script: string): string;
export declare function preflightEvaluateScript(script: string): {
    ok: true;
} | {
    ok: false;
    message: string;
};
