/**
 * `browser find --css <sel>` — structured CSS query.
 *
 * Returns every match of a selector as a JSON envelope agents can read
 * without parsing free-text snapshot output. Each entry carries two
 * identifiers — a numeric `ref` (matching the snapshot contract) and a
 * stable 0-based `nth` — so the agent can act on a specific result via
 * either path:
 *
 *   browser click <ref>              // when ref is numeric
 *   browser click "<sel>" --nth <n>  // always works
 *
 * Refs are *allocated on the spot* for matched elements that were not
 * tagged by a prior snapshot: `data-opencli-ref` is set on the element
 * and a fingerprint is written into `window.__opencli_ref_identity`
 * (same shape the snapshot uses). That makes `find` a first-class entry
 * point to the ref system — agents can skip running `browser state`
 * when they already know the selector.
 *
 * Attributes are whitelisted to keep output small and high-signal.
 * Invisible elements are still returned so agents can reason about
 * offscreen vs truly-missing targets.
 *
 * When a matched element is a compound form control (date-like input,
 * select, file input), the entry gains a `compound` field with the
 * rich view from `compound.ts`. This is what kills the three biggest
 * agent-fail modes on form pages (wrong date format, guessed options,
 * re-uploaded files) without forcing agents to probe further.
 */
import { type CompoundInfo } from './compound.js';
/** Whitelist of attributes surfaced per entry. Keep small; agents do not need full DOM dumps. */
export declare const FIND_ATTR_WHITELIST: readonly ["id", "class", "name", "type", "placeholder", "aria-label", "title", "href", "value", "role", "data-testid"];
export interface FindEntry {
    /** Zero-based position within the match set — pair with `--nth` on downstream commands. */
    nth: number;
    /**
     * Numeric data-opencli-ref. Find assigns one if the element was not
     * tagged by a prior snapshot, so downstream `browser click <ref>` works
     * directly off the find output without requiring `browser state` first.
     */
    ref: number;
    tag: string;
    role: string;
    text: string;
    attrs: Record<string, string>;
    visible: boolean;
    /**
     * Rich view for date / time / datetime-local / month / week / select /
     * file inputs. Omitted (undefined) for all other element types. See
     * `compound.ts` for the shape.
     */
    compound?: CompoundInfo;
}
export interface FindResult {
    matches_n: number;
    entries: FindEntry[];
}
export interface FindError {
    error: {
        code: 'invalid_selector' | 'selector_not_found' | 'semantic_not_found';
        message: string;
        hint?: string;
    };
}
export interface FindOptions {
    /** Max entries returned. Default 50 — enough to pick from without flooding context. */
    limit?: number;
    /** Max chars of trimmed text per entry. Default 120. */
    textMax?: number;
}
export interface SemanticFindOptions extends FindOptions {
    role?: string;
    name?: string;
    label?: string;
    text?: string;
    testid?: string;
}
/**
 * Build the browser-side JS that performs the CSS query and emits the
 * FindResult (or FindError) envelope. Evaluated inside `page.evaluate`.
 */
export declare function buildFindJs(selector: string, opts?: FindOptions): string;
export declare function buildSemanticFindJs(opts: SemanticFindOptions): string;
export declare function isFindError(result: unknown): result is FindError;