import { WebElement } from '@civitas-cerebrum/element-repository';
/**
 * Utility class to handle standardized waiting logic across the framework.
 *
 * All waits go through `Element.waitFor` rather than raw Playwright so the
 * framework works consistently across web and platform drivers.
 */
export declare class Utils {
    static readonly SOFT_PROBE_MS = 2000;
    private readonly timeout;
    constructor(timeout?: number);
    /** Returns the current timeout value. */
    getTimeout(): number;
    softProbe(element: WebElement, state?: 'visible' | 'attached', timeout?: number): Promise<void>;
    /**
     * Standardized wait logic for element states.
     * Throws on timeout as of 0.3.7; pass `optional: true` to get the
     * pre-0.4 soft behavior (resolves `false`, logs a warning).
     * If the resolver yields multiple elements (strict mode violation),
     * the wait retries on the first matched element and logs loudly.
     *
     * @param element  - An `Element` to wait on.
     * @param state    - The state to wait for. Defaults to `'visible'`.
     * @param timeout  - Per-call timeout override. Falls back to the instance timeout when omitted.
     * @param optional - When `true`, a timeout resolves `false` instead of throwing.
     * @returns `true` when the state was reached; `false` only when `optional` and the wait timed out.
     */
    waitForState(element: WebElement, state?: 'visible' | 'attached' | 'hidden' | 'detached', timeout?: number, optional?: boolean): Promise<boolean>;
    /**
     * Deliberate pause for `ms` milliseconds. Named `pace` — NOT `wait` — to
     * signal intentional timing control (settling a debounce, spacing
     * rapid-fire actions) rather than a missing wait-for-state. Whenever you are
     * actually waiting for the app to reach a condition, prefer `waitForState`
     * or a web-first assertion; reach here only for genuinely time-based pacing.
     */
    pace(ms: number): Promise<void>;
    /**
     * Runs `fn` `times` times in sequence — passing the zero-based iteration
     * index — and collects each result. With `intervalMs`, paces BETWEEN
     * iterations (never before the first or after the last). The
     * intent-revealing form of a hand-rolled "do X rapidly N times" loop
     * (repeated swatch clicks, double-submit probes, retrying a flaky toggle).
     *
     * @returns the array of every iteration's resolved result, in order.
     */
    repeat<T>(fn: (index: number) => Promise<T> | T, times: number, options?: {
        intervalMs?: number;
    }): Promise<T[]>;
    /**
     * Terminal handling for a timed-out wait: soft (warn + `false`) when the
     * wait was optional, an error carrying the original cause otherwise.
     */
    private handleWaitTimeout;
}