/**
 * Stealth-by-default Playwright wrapper.
 *
 * Bare headless Chromium is detected by every serious anti-bot stack
 * (Akamai, DataDome, PerimeterX, Cloudflare Turnstile). Defaulting to
 * stealth costs nothing on unprotected sites and is the only thing
 * that works on protected ones. Scrapers can still opt out via
 * `browser.raw`.
 */
import type { Browser, BrowserContext, Page } from "playwright";
export interface ContextOptions {
    readonly userAgent?: string;
    readonly locale?: string;
    readonly timezoneId?: string;
    readonly viewport?: {
        width: number;
        height: number;
    };
    /** Defaults to 2 (Retina-like). Set to 1 for smaller screenshots. */
    readonly deviceScaleFactor?: number;
    readonly extraHTTPHeaders?: Record<string, string>;
    /** Disable stealth init script for this context only. Rarely needed. */
    readonly stealth?: boolean;
}
export interface ScrollOptions {
    /** Pixels per scroll step. Default 800. */
    readonly step?: number;
    /** Delay between steps in ms. Default 500. */
    readonly delay?: number;
    /** Safety ceiling — max scroll iterations. Default 50. */
    readonly maxScrolls?: number;
    /** Stop after this many consecutive iterations with no height change. Default 3. */
    readonly idleRounds?: number;
}
export interface ScrollResult {
    readonly scrolls: number;
    readonly finalHeight: number;
    readonly hitMax: boolean;
}
/**
 * Browser facade exposed as `ctx.browser`. Every new page/context comes
 * pre-stealthed with `en-IN` / `Asia/Kolkata` defaults. Pass `{ locale,
 * timezoneId }` to target a different region — `Accept-Language` and
 * `navigator.languages` are both derived from `locale`, so they stay
 * mutually consistent.
 */
export interface BrowserFacade {
    /** Open a stealth page (creates an isolated context per call). */
    newPage: (options?: ContextOptions) => Promise<Page>;
    /** Open a stealth context. Pass overrides; defaults are merged in. */
    newContext: (options?: ContextOptions) => Promise<BrowserContext>;
    /** Auto-scroll until the page stops growing (infinite-scroll feeds). */
    autoScroll: (page: Page, options?: ScrollOptions) => Promise<ScrollResult>;
    /** Underlying Playwright Browser for power users. */
    readonly raw: () => Promise<Browser>;
    /** Close everything. */
    close: () => Promise<void>;
}
export interface BrowserFacadeDeps {
    readonly log: {
        info: (msg: string, data?: unknown) => void;
        warn: (msg: string, data?: unknown) => void;
    };
}
/**
 * Build a lazy, stealth-by-default BrowserFacade.
 *
 * The Playwright browser is launched on first use. All contexts get
 * the stealth init script unless `{ stealth: false }` is passed.
 */
export declare function makeBrowserFacade(deps: BrowserFacadeDeps): BrowserFacade;