Runs PROXYLESS by default. To use a proxy, pass either proxy_url
    ('http://user:pass@host:port') or proxy_server[+username/password].
    no_proxy=True forces proxyless even if an env/default proxy is configured.

    persistent: keep cookies/localStorage in a profile dir across runs.
    headless: override the configured default (None = use the default).
    record_har: capture a full network HAR (export with browser_har_export).
    har_url_filter: glob to scope what the HAR records (e.g. '**/api/**' or
        '**/students/**') so it excludes login/captcha/static noise; default = all.
    storage_state: path to a saved cookies/localStorage JSON to reload.
    (For a screen recording, use browser_start_recording / browser_stop_recording → GIF.)
    Most tools auto-create a default session, so calling this is optional.
    

    Auto-creates a session if none exists.
    

    Use this after triggering an OAuth / SSO flow (Google Sign-In, GitHub OAuth,
    etc.) or any action that calls window.open() or opens a target=_blank link.
    The tool waits up to timeout_ms for the new window to open, then makes it the
    active page and returns its ARIA snapshot. To go back to the original tab
    afterward, use browser_tabs(action='select', index=0).

    This is the primary way to 'see' a page: it lists actionable elements (roles +
    names + refs) without CSS/markup noise. Pass a ref from here to click/type/hover.
    Frame-hosted elements get prefixed refs like 'f1e36' (iframe 1, element 36).
    Shadow DOM elements appear with plain eN refs — the locator engine pierces them.
    

    frame_ref: a frame id ('f1'), an element ref inside the frame ('f1e36'), or the
    <iframe> element's own ref ('e81'). Returns the frame's ARIA tree with refs
    rewritten to 'fNeM' form so they're directly usable with click/type/etc.

    Call this before (or immediately after) clicking a download button.
    The first download event is captured, saved to save_dir, and the
    absolute file path is returned. timeout_ms: max wait (default 30s).

    Works on contenteditable rich-text editors (TipTap, Quill, ProseMirror)
    where browser_type / fill() is a no-op. Also the escape hatch when a
    coordinate click focused an iframe field and you need to type into it.
    Pattern: browser_mouse_click(x, y) to focus → browser_keyboard_type(text).
    delay: ms between keystrokes (simulates human typing speed).
    Returns a snapshot.

    text        — text to become visible (searched across all frames including iframes).
    text_gone   — text to disappear.
    selector    — CSS/Playwright selector to become visible.
    url         — URL glob/regex to wait for (SPA client-side navigation).
    network_idle — wait until no network requests for 500ms (SPA render complete).
    time        — wait N seconds unconditionally.
    timeout_ms  — max wait in ms (default 30 000).
    

    frame_ref: run the JS INSIDE a child frame instead of the top document. Accepts
    a frame id ('f1'), an element ref inside the frame ('f1e36'), or an <iframe>
    element ref ('e81'). This works for CROSS-ORIGIN frames too — the code runs in
    the frame's own context (unlike top-frame JS reaching in via contentDocument,
    which the browser blocks). This is the fix for "Permission denied to access
    property document on cross-origin object".
    Examples: 'document.title'  |  '() => window.location.href'
    

    direction: 'up' | 'down' | 'left' | 'right'. amount: pixels (default 300).
    ref: if given, scrolls that element into view (direction/amount ignored).
    Use this to trigger lazy-loaded content or reveal off-screen elements.
    Returns a snapshot.

    Stops when the page height stops growing (infinite scroll exhausted or real
    bottom reached). max_scrolls: safety cap. wait_ms: pause per step.
    Returns a snapshot of the final state.

    Each entry: {url, closed, messages: [{dir: 'sent'|'received', data: str}]}.
    url_contains: filter to connections whose URL includes this substring.
    Useful for real-time apps (trading dashboards, chat, live data feeds) that
    deliver state over WebSocket rather than HTTP.

    NOTE: This CLOSES the session — Playwright only flushes the HAR buffer when
    the browser context closes. The session must have been created with record_har=True.

    output_path: copy the finished HAR to this path (e.g. 'results/run1.har').
        If omitted, the HAR stays at its auto-generated path under data/har/.

    Non-destructive checkpoint pattern (to keep browsing after capturing traffic):
      1. browser_storage_state(path='data/checkpoint.json')   # save auth/cookies
      2. browser_har_export()                                  # closes session, flushes HAR
      3. browser_new_session(storage_state='data/checkpoint.json')  # resume
    

    kind: 'turnstile' | 'recaptcha_v2' | 'recaptcha_v3' | 'hcaptcha' | 'funcaptcha'.
    website_key is auto-detected from the DOM if omitted (for FunCaptcha that's the
    public key). provider defaults to the configured one (needs that provider's API
    key in the environment). Returns the solved token.

    recaptcha_v3: pass page_action (must match the site's grecaptcha.execute action)
      and optionally min_score (0.1–0.9); the token is injected and grecaptcha.execute
      is overridden to return it.
    funcaptcha (Arkose): funcaptcha_subdomain (the Arkose 'surl') and funcaptcha_data
      (the dynamic 'blob' JSON string) are passed through for sites that require them.
    

    No browser or session needed — this is a pure computation tool.
    Use it when a site uses an authenticator app (Google Authenticator, Authy, etc.)
    as the second factor. The secret is the base32 string shown during 2FA setup
    (usually labeled 'secret key' or encoded in the QR code's otpauth:// URI).

    digits: code length (default 6). interval: time step in seconds (default 30).
    Returns the current 6-digit (or N-digit) TOTP code as a string.
    

    Returns the markdown string. If output_path is given, the markdown is written to
    that file and {path, chars} is returned instead — so you can pick a path and fetch
    the content from there. You (the agent) do any further structuring/extraction.
    

    Stop with browser_stop_recording, which encodes a smooth real-time MP4/WebM/GIF
    via ffmpeg (Camoufox can't write native video). Great for README/marketing demos.
    The real capture rate is capped by how fast the browser serves screenshots.

    Format is inferred from `path`'s extension: .mp4 (H.264, default), .webm, or .gif.
    `fps`: output frame rate (MP4/WebM target 30; GIF capped to 15). Playback is
    real-time. `also_gif=True` additionally writes a sibling .gif next to a video
    (handy: an .mp4 for quality + a .gif that autoplays inline on GitHub).

    permissions: list of permission names, e.g. ['geolocation'], ['notifications'],
        ['camera'], ['microphone'], ['clipboard-read'], ['clipboard-write'].
    origin: restrict the grant to a specific origin (e.g. 'https://example.com');
        omit to apply session-wide.

    Call this before navigating to a page that requests permissions, or immediately
    when a permission prompt appears (it will dismiss the prompt automatically).