Patterns use Chrome's wildcard syntax: ``*googletagmanager.com*``,
    ``*.png``, ``https://analytics.example.com/*``. Pass an empty list
    or call ``unblock_all_urls`` to remove all blocks.
    

    Waits up to ``timeout`` seconds for the challenge iframe and then clicks
    the checkbox every ``click_delay`` seconds until the input disappears
    or gets a value. Raises TimeoutError if the challenge cannot be solved
    in time.
    

    Use this before ``run_lighthouse`` if you want to prompt the user to
    install it.
    

    Uses the same technique React's synthetic-event system expects so
    controlled components actually see the change. Previously we called
    ``document.execCommand`` which is deprecated and invisible to
    React/Vue/Angular state.
    

    CDP ``setUserAgentOverride`` has no explicit "clear" command - and
    sending an empty string makes Chrome actually send ``User-Agent:``
    (empty), which is *more* fingerprintable than the real UA. Instead
    we query ``navigator.userAgent`` from a fresh evaluation (Chrome
    returns the real UA there, not the override) and set that back.
    

    Accepts a CSS selector, the numeric id from ``get_interaction_tree``
    (e.g. ``"12"`` -> ``[data-zendriver-id="12"]``), or ``text`` to find
    by visible text content.
    

    Resolves the cached ``backend_node_id`` to a remote object, then
    dispatches a native element click. Raises ``AccessibilityUidError``
    if the uid is unknown or the node was removed since the snapshot.
    

    Use when a page wraps a real ``<button>`` / ``[role="radio"]`` /
    ``[role="checkbox"]`` in one or more open shadow roots
    (``<nes-button>``, ``<sds-radio>``, ``<lion-input>`` and friends).
    ``selector`` should match the outer custom element in the light
    DOM; this tool then recurses through every nested ``shadowRoot``
    up to ``max_depth`` levels and dispatches a composed click
    sequence on the first interactive descendant it finds.

    Returns an error when the host isn't found or no inner interactive
    element lives inside its shadow tree.
    

    Accepts ``http://host:port``, ``socks5://host:port``, or Chrome's
    full proxy rule syntax. Pass a ``user_data_dir`` to preserve the
    logged-in session across the restart - without it you start fresh.
    

    Returns a condensed JSON tree - each node has ``tag``, ``id``,
    ``role``, ``type``, ``text``, a ``light`` array of light-DOM
    children and a ``shadow`` array for the element's shadowRoot
    children (when open). Use this when ``find_buttons`` /
    ``find_inputs`` aren't surfacing a control you can see on the
    page; the result tells you the exact nested-host path so you
    can target ``click_shadow`` or chain custom queries.
    

    ``media`` is typically ``""`` (default), ``"screen"``, or ``"print"``.
    ``prefers_color_scheme`` is ``""`` (default), ``"light"``, or ``"dark"``.
    

    Useful for scheduling follow-up actions without guessing.
    

    IMPORTANT: Do NOT use 'return' statements directly in your script.
    The script is automatically wrapped to capture the result.

    Examples:
        Good: document.title
        Good: (function() { const x = 1 + 1; return x; })()
        Bad:  return document.title  // SyntaxError!

    For complex scripts, wrap in an IIFE:
        (function() {
            const data = [];
            // ... your code ...
            return data;
        })()
    

    Compatible with the "Edit This Cookie" Chrome extension export format
    and Playwright's storage state shape (just the cookies slice).
    Use ``import_cookies`` on another session to restore.
    

    Uses the default ``frame-%06d.jpg`` / ``frame-%06d.png`` pattern that
    ``start_screencast`` writes. ``fps`` is the playback rate (not the
    capture rate). Requires ffmpeg.
    

    ``error_reason`` must match a CDP ``Network.ErrorReason`` member
    (``Failed``, ``Aborted``, ``TimedOut``, ``AccessDenied``,
    ``ConnectionClosed``, ``ConnectionReset``, ``ConnectionRefused``,
    ``ConnectionAborted``, ``ConnectionFailed``, ``NameNotResolved``,
    ``InternetDisconnected``, ``AddressUnreachable``, ``BlockedByClient``,
    ``BlockedByResponse``).
    

    Reports which selectors succeeded and which were missing so the
    caller can tell partial fills from full ones. Fields are cleared
    before typing so values don't concatenate with existing content.
    

    ``limit`` caps the number of summary rows; the total count is always
    accurate. Zendriver's ``select_all`` raises ``TimeoutError`` after
    ~10s on zero matches, which we catch and translate to a clean
    "no elements found" message.
    

    Walks both the light DOM and every open shadow root, so buttons
    hidden inside custom elements like ``<nes-button>`` or
    ``<sds-cta>`` show up. Recognises native tags (button, a, input,
    summary) plus ARIA roles (button, link, checkbox, radio, switch,
    menuitem, tab, option, treeitem) and cursor=pointer elements
    with an onclick handler. Each entry shows the host's CSS
    selector; for shadow-wrapped buttons use ``click_shadow`` to
    reach the inner interactive element.
    

    Walks both the light DOM and every open shadow root. Recognises
    ``<input>``, ``<textarea>``, ``role=textbox/searchbox/combobox``,
    ``[contenteditable="true"]`` and custom elements whose tag name
    suggests an input (contains "input" or "field"). ``filter_type``
    is a case-insensitive substring match against the input's type
    attribute or ARIA role.
    

    Each node looks like ``{"uid": "ax_1b2c", "role": "button",
    "name": "Submit", "children": [...]}``. The uid can be passed to
    ``click_by_uid`` for deterministic interaction.

    - ``max_nodes``: cap the node count to keep the response small.
    - ``interesting_only``: skip ignored/structural nodes (``none``,
      ``generic``, ``InlineTextBox``, ``StaticText``) while keeping
      their children, so the tree stays compact without losing content.
    

    The first line reports the slice, total size, and the next offset
    when more content is available.
    

    Intentionally limited: HTTP-only and other-origin cookies are
    invisible here. For full-fidelity cookie access use
    ``list_all_cookies`` / ``export_cookies`` from the ``cookies``
    module instead.
    

    The ids double as selectors for click/type tools. ``limit`` caps
    the element count.
    

    Reads ``document.title`` and ``location.href`` via ``page.evaluate``
    instead of trusting zendriver's cached ``tab.target`` metadata,
    which can be stale right after navigation - and on some zendriver
    versions ``tab.title`` is a coroutine method, so ``getattr`` would
    return the bound method repr string.
    

    Accepted names are listed by ``list_permission_names``. Any name
    that resolves to a full CDP enum key is also accepted (e.g.
    ``VIDEO_CAPTURE`` or ``videoCapture``).
    

    Accepts a CSS selector, the numeric ID from ``get_interaction_tree``,
    or visible text. ``move_duration`` is how long the mouse takes to
    reach the target (default 0.4s). Text-mode is shadow-DOM aware:
    the walker finds the tightest interactive element matching the
    text (descending into nested shadowRoots when needed) and aims
    the cursor at its composed viewport rect, so clicks land on the
    real handler inside custom elements like ``<nes-button>``.
    

    If ``selector`` is provided the element is focused first via a
    human click. 220 wpm is a fast but plausible adult typist.
    

    Silently skips entries that fail the ``CookieParam`` schema so a
    partial restore still works. Existing cookies with the same
    (name, domain, path) triple are overwritten by Chrome.
    

    Fast probe - use before ``bypass_cloudflare`` to skip the click cycle
    when the page already passed.
    

    ``url_pattern`` uses Unix glob syntax (``*``, ``?``), matched against
    the full request URL. ``body`` is UTF-8 text (cap: 10 MiB to prevent
    RAM exhaustion). Returns a rule id; pass it to
    ``stop_interception(rule_id)`` or call with no args to clear all.
    

    Uses real browser key events, not synthetic JS dispatch - so native
    form-submit semantics, browser shortcuts, and IME all behave as
    they would with a human keyboard. When ``selector`` is given we
    focus that element first.

    Recognised names: ``Enter``, ``Tab``, ``Escape``, ``Backspace``,
    ``Delete``, ``ArrowUp/Down/Left/Right``, ``Space``, ``Home``, ``End``,
    ``PageUp``, ``PageDown``. Any single character (e.g. ``"a"``) is also
    accepted.
    

    - ``categories``: subset of ``performance``, ``accessibility``,
      ``best-practices``, ``seo``, ``pwa``. Defaults to the first four.
    - ``form_factor``: ``"mobile"`` or ``"desktop"``.
    - ``output_path``: where to save the JSON report. Empty => temp file.

    The browser must have been started with remote-debugging exposed,
    which zendriver does by default.
    

    Checks for: HTTPS, CSRF protection, password security, mixed content,
    inline scripts, SRI (Subresource Integrity), forms, sensitive data exposure,
    and JavaScript security patterns.
    

    Args:
        save_path: Optional path to also save to disk at full
            resolution (format from the extension).
        full_resolution: Return the image without downscaling.
    

    Uses JavaScript ``window.scrollBy`` directly. The earlier implementation
    called zendriver's ``scroll_down`` which interprets its argument as a
    *percentage* of the viewport and animates via
    ``Input.synthesizeScrollGesture`` - turning e.g. 500 into five
    viewport-heights of smooth scrolling.
    

    Honest success / failure reporting: if no element matches the
    selector we raise ``ElementNotFoundError`` instead of silently
    no-op'ing with a fake "Scrolled to: ..." message.
    

    Cannot set HTTP-only or cross-origin cookies. Prefer
    ``import_cookies`` for restoring full sessions across origins.
    

    ``1.0`` disables throttling, ``4.0`` is DevTools' "4x slowdown",
    ``20.0`` roughly emulates a low-end phone.
    

    Call ``list_devices`` to see available profile keys
    (e.g. ``iphone-15-pro``, ``pixel-8``, ``ipad-pro``, ``desktop-1080p``).
    Also sets a matching User-Agent when the profile provides one.
    

    Affects navigator.language, Intl APIs, and Accept-Language defaults.
    Pass an empty string to restore the system locale.
    

    Options: ``offline``, ``slow-3g``, ``fast-3g``, ``4g``,
    ``no-throttling``. See ``list_network_profiles`` for the numeric
    values.
    

    Pass an empty string to restore the system timezone.
    

    Applies to every subsequent request on the current tab until
    ``clear_user_agent`` is called or the tab closes. ``platform`` should
    match the UA (e.g. ``"Win32"`` for a Windows UA).
    

    ``width`` / ``height`` in CSS pixels. ``device_scale_factor`` is DPR
    (1.0 for standard, 2.0 for Retina, etc.). ``mobile`` toggles the
    meta-viewport / overlay-scrollbar behaviour.
    

    - ``fmt``: ``"jpeg"`` (smaller) or ``"png"`` (lossless).
    - ``quality``: 0-100, JPEG only.
    - ``max_width``: frames are downscaled to this width if larger.
    - ``every_nth_frame``: skip frames between captures (1 = every frame).
    

    ``categories`` is a comma-separated CDP category filter; empty string
    uses the DevTools Performance-panel default profile. Only one trace
    can be active per tool instance at a time.
    

    Returns the absolute file path. If ``file_path`` is empty, writes to
    a timestamped file in the system temp directory. The output matches
    the format that Chrome DevTools' "Load profile" accepts.

    Handlers and state are cleared via ``finally`` so a failed
    ``tracing.end()`` or a late ``tracingComplete`` never leaves the
    tool stuck on "a trace is already in progress" for the rest of the
    process.
    

    Uses ``form.requestSubmit()`` so React/Vue/Formik ``onSubmit``
    handlers fire and HTML validation runs, falling back to a bubbling
    ``submit`` event and finally ``form.submit()`` for ancient pages.
    Returns an error if the selector matches no form.
    

    The output is the same ``.heapsnapshot`` format Chrome DevTools saves,
    loadable via DevTools > Memory > Load.
    

    By default the field is cleared first (``replace=True``). Set
    ``replace=False`` to append to the existing value.
    

    Args:
        selector: CSS selector to wait for
        timeout: Maximum time to wait in seconds (default: 30s for SPAs)
        visible: If True, also checks element is visible (not hidden)
    

    Useful after triggering actions that cause API calls.

    Args:
        timeout: Maximum time to wait in seconds
        idle_time: How long network must be idle to consider it done
    

    Only log entries with a resolved status code are considered, so this
    returns after the server replied, not the moment Chrome sent the
    request. ``url_pattern`` is a case-insensitive substring of the full
    URL; ``method`` optionally filters on HTTP verb.