import type { ElementHandle, KeyboardTypeOptions, KeyInput, KeyPressOptions, MouseButton, Page } from "puppeteer-core";
import { ToolAbortError } from "../tool-errors.js";
import { type UploadRoute, type UploadStaging } from "./upload-files.js";
/** Options accepted by coordinate-based mouse clicks. */
export interface ClickAtOptions {
    /** Mouse button to press. */
    button?: MouseButton;
    /** Number of clicks to dispatch. */
    clickCount?: number;
}
/** Options accepted by pointer movement. */
export interface MouseMoveOptions {
    /** Number of intermediate movement events. */
    steps?: number;
}
/** Options accepted by mouse button transitions. */
export interface MouseButtonOptions {
    /** Mouse button to press or release. */
    button?: MouseButton;
}
/** Options accepted by element highlighting. */
export interface HighlightOptions {
    /** Time to keep the highlight visible in milliseconds. */
    duration?: number;
}
/** Options accepted by element or page scrolling. */
export interface ScrollOptions {
    /** Scroll one matching element instead of the page. */
    selector?: string;
}
/** A browser element handle with omp's additional interaction methods. */
export type InteractionHandle = ElementHandle & {
    dblclick(): Promise<void>;
    check(): Promise<void>;
    uncheck(): Promise<void>;
    highlight(options?: HighlightOptions): Promise<void>;
};
type ActionabilityResult = {
    ok: true;
    x: number;
    y: number;
} | {
    ok: false;
    reason: string;
    coveredBy?: string;
};
/** A click aborted while its element was still refused; `refusal` names the last failed check. */
export declare class ClickRefusedError extends ToolAbortError {
    readonly refusal: string;
    constructor(refusal: string, options?: ErrorOptions);
}
/**
 * Text entry aborted after input reached the page; `progress` says what the field may already hold.
 * The per-op timeout reports this instead of an actionability hint, since the element did take input.
 */
export declare class TypingInterruptedError extends ToolAbortError {
    readonly progress: string;
    constructor(progress: string, options?: ErrorOptions);
}
/**
 * Page function (self-contained; serialisable via `.toString()`): whether `descendant` is `ancestor` or
 * renders inside it — its flat-tree ancestry, which follows slot assignment into shadow trees and climbs
 * shadow-root boundaries out to their hosts, where `Node.contains` stops.
 */
export declare function composedContains(ancestor: unknown, descendant: unknown): boolean;
/**
 * Return a visible point relative to the element's box, or explain why it cannot receive a click.
 * A left click on one of the control's own `<label>`s counts as on-target, since the label forwards it.
 */
export declare function isClickActionable(handle: ElementHandle, signal?: AbortSignal, options?: Pick<ClickAtOptions, "button">): Promise<ActionabilityResult>;
/**
 * Click an element only after verifying the dispatched point is not occluded, then confirm the browser
 * delivered the click to it: the target got the `mousedown` or `click` (a label's forwarded `click` counts
 * for its control), or the page consumed its `pointerdown` with `preventDefault()`, which suppresses the
 * mouse events after it. A disabled control gets only an unconsumed `pointerdown` and an inert subtree
 * nothing, so a click the page never saw fails instead of reporting success.
 */
export declare function clickElement(handle: ElementHandle, label: string, signal?: AbortSignal, options?: ClickAtOptions): Promise<void>;
/** Focus a text-entry target, then type `text` so an abort stops before the next key; see {@link typeKeys}. */
export declare function typeIntoElement(handle: ElementHandle, text: string, signal?: AbortSignal, options?: Readonly<KeyboardTypeOptions>): Promise<void>;
/**
 * Focus a field that can take text, clear any existing value, then retype. A colour, date, time or
 * range input gets its value set the way its picker would, and refuses one it rejects. A
 * contenteditable element has its contents selected and replaced by one text insertion (or deleted
 * by Backspace for an empty value), as a paste would.
 *
 * Every step is a DOM evaluation or an input dispatch, so this works on tabs
 * that produce no animation frames — unlike Puppeteer's `Locator.fill`, whose
 * viewport/stability/enabled preconditions wait on `requestAnimationFrame`
 * and `IntersectionObserver` callbacks that a backgrounded headless tab never
 * delivers (#12892). Typing stops at the next key once `signal` aborts.
 */
export declare function fillViaHandle(handle: ElementHandle, value: string, signal?: AbortSignal): Promise<void>;
/**
 * Resolve text-query matches to the first match the browser shows on screen, in document order. A match
 * shown only as a strip at an edge counts once scrolling it into view lets the browser hit its interior,
 * as with a strip a scroll container leaves; one an overlay covers stays covered there. When none is on
 * screen, off-screen matches are scrolled into view in document order and the first one shown wins;
 * failing that, the first one a click could be aimed at, then the first match, so the click itself reports
 * what stops it.
 */
export declare function resolveActionableQueryHandlerClickTarget(handles: ElementHandle[], signal?: AbortSignal): Promise<ElementHandle | null>;
/** Click the actionable match chosen for a Puppeteer text query handler. */
export declare function clickQueryHandlerText(page: Page, selector: string, label: string, timeoutMs: number, signal?: AbortSignal, options?: ClickAtOptions): Promise<void>;
/** Set a native checkable control or ARIA switch to the requested state idempotently. */
export declare function setElementChecked(handle: ElementHandle, checked: boolean, label: string, signal?: AbortSignal): Promise<void>;
/** Draw a temporary inert outline around an element and remove it after the requested duration. */
export declare function highlightElement(handle: ElementHandle, options?: HighlightOptions, signal?: AbortSignal): Promise<void>;
/**
 * Select `<select>` options by value, then by visible label, and return the values this call
 * selected. An exact value match always wins over a label, so value-based calls keep their
 * meaning. A single `<select>` takes the first matching value. A value that matches no option
 * throws before the select is touched, so a typo never commits the browser's default option.
 */
export declare function selectElementOptions(handle: ElementHandle, values: string[], label: string, signal?: AbortSignal): Promise<string[]>;
/**
 * An upload whose target is found. Finding it runs under the action deadline; `deliver` hands over the files, which for
 * streamed contents takes time in proportion to their size, so it runs under its own, longer one.
 */
export interface PreparedUpload {
    /** Bytes `deliver` hands over. */
    readonly bytes: number;
    deliver(signal: AbortSignal): Promise<void>;
    /** Release what finding the target held: a caught chooser's input, cancelled when it was never filled. */
    dispose(): Promise<void>;
}
/** Prepare an upload into a file input: open the files and check the input takes that many. */
export declare function prepareInputUpload(input: ElementHandle, absolutePaths: string[], route: UploadRoute, staging: UploadStaging, signal?: AbortSignal): Promise<PreparedUpload>;
/**
 * Find what takes an upload through `handle`: the file input itself, the chooser its click opens, or else the element
 * as a drop zone. `route` is how the browser gets the files; see {@link UploadStaging.route}.
 */
export declare function prepareElementUpload(page: Page, handle: ElementHandle, absolutePaths: string[], label: string, route: UploadRoute, staging: UploadStaging, signal?: AbortSignal): Promise<PreparedUpload>;
/** Press a keyboard key without releasing it; a press cut off on its way is released, not left held. */
export declare function keyDown(page: Page, key: KeyInput, signal?: AbortSignal): Promise<void>;
/** Release a keyboard key previously pressed with keyDown. */
export declare function keyUp(page: Page, key: KeyInput, signal?: AbortSignal): Promise<void>;
/** Install {@link CANCELLED_RELEASE_GUARD} in this page's documents, current and future. */
export declare function installCancelledReleaseGuard(page: Page): Promise<void>;
/**
 * Release a mouse button off the page so the press activates nothing it pressed: the page gets its `mouseup`,
 * and the click Chrome then fires on the document root is swallowed (see {@link CANCELLED_RELEASE_GUARD}). Sent
 * at once and not awaited, for the same reason as {@link releaseKeys}.
 */
export declare function releaseButtonOffPage(page: Page, options: MouseButtonOptions): void;
/**
 * Press a key or a `+`-joined combo (`Enter`, `Shift+Tab`, `Meta+a`): the leading
 * keys go down in order, the last key is pressed with `options`, then all of them
 * are released in reverse. An aborted press sends no further key down and still
 * releases each key whose press went out, so no modifier stays held for the user's
 * next key.
 */
export declare function pressKey(page: Page, combo: string, options?: KeyPressOptions, signal?: AbortSignal): Promise<void>;
/** Move the page pointer to viewport coordinates. */
export declare function mouseMove(page: Page, x: number, y: number, options?: MouseMoveOptions, signal?: AbortSignal): Promise<void>;
/** Press a mouse button at the current pointer position; a press cut off on its way is released off the page. */
export declare function mouseDown(page: Page, options?: MouseButtonOptions, signal?: AbortSignal): Promise<void>;
/** Release a mouse button at the current pointer position. */
export declare function mouseUp(page: Page, options?: MouseButtonOptions, signal?: AbortSignal): Promise<void>;
/** Click the page at viewport coordinates. */
export declare function clickAt(page: Page, x: number, y: number, options?: ClickAtOptions, signal?: AbortSignal): Promise<void>;
/** Drag with the left button from `start` to `end`; cancellation before the final release drops off-page. */
export declare function dragBetween(page: Page, start: {
    x: number;
    y: number;
}, end: {
    x: number;
    y: number;
}, signal?: AbortSignal): Promise<void>;
/** Queue one raw mouse-wheel event without waiting for scroll settlement. */
export declare function wheel(page: Page, deltaX: number, deltaY: number, signal?: AbortSignal): Promise<void>;
export {};