From cebe721b881f8be555075d46bb2987e9df0a9daa Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 8 Apr 2026 10:52:31 +0000
Subject: [PATCH 1/3] Initial plan


From 7a37092206694461e339b40faa7286f2790749f1 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 8 Apr 2026 11:08:38 +0000
Subject: [PATCH 2/3] Add browser_control module, tests, docs, and example

Agent-Logs-Url: https://github.com/HyperionGray/python-chrome-devtools-protocol/sessions/f5aedfd0-e970-4dc1-bc96-e614a946247f

Co-authored-by: P4X-ng <223870169+P4X-ng@users.noreply.github.com>
---
 cdp/browser_control.py              | 722 ++++++++++++++++++++++++++++
 docs/browser_control.rst            | 199 ++++++++
 docs/index.rst                      |   1 +
 docs/overview.rst                   |  44 +-
 examples/browser_control_example.py | 120 +++++
 test/test_browser_control.py        | 452 +++++++++++++++++
 6 files changed, 1529 insertions(+), 9 deletions(-)
 create mode 100644 cdp/browser_control.py
 create mode 100644 docs/browser_control.rst
 create mode 100644 examples/browser_control_example.py
 create mode 100644 test/test_browser_control.py

diff --git a/cdp/browser_control.py b/cdp/browser_control.py
new file mode 100644
index 0000000..149ebf2
--- /dev/null
+++ b/cdp/browser_control.py
@@ -0,0 +1,722 @@
+"""
+Browser Control Module
+
+High-level browser automation API built on top of the CDP domain modules and
+``CDPConnection``. This module provides Playwright-style helpers for common
+browser automation tasks: element selection, clicking, typing, waiting,
+navigation, and screenshots.
+
+All methods in this module are coroutines that require a connected
+``CDPConnection`` instance.
+
+Example::
+
+    import asyncio
+    from cdp.connection import CDPConnection
+    from cdp import browser_control as bc
+
+    async def main():
+        async with CDPConnection("ws://localhost:9222/devtools/page/ID") as conn:
+            await bc.navigate(conn, "https://example.com")
+            await bc.wait_for_load(conn)
+
+            node = await bc.query_selector(conn, "h1")
+            text = await bc.get_text(conn, node)
+            print(text)
+
+            await bc.click(conn, "a")
+            await bc.type_text(conn, "input[name='q']", "hello world")
+            data = await bc.screenshot(conn)
+            with open("page.png", "wb") as f:
+                f.write(data)
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import typing
+
+from cdp import dom, input_, page, runtime
+from cdp.connection import CDPConnection
+
+__all__ = [
+    # Navigation
+    "navigate",
+    "reload",
+    "go_back",
+    "go_forward",
+    "wait_for_load",
+    # Element selection
+    "query_selector",
+    "query_selector_all",
+    # Element interaction
+    "click",
+    "double_click",
+    "hover",
+    "type_text",
+    "clear_and_type",
+    "press_key",
+    "focus",
+    "select_option",
+    # Element inspection
+    "get_text",
+    "get_attribute",
+    "get_bounding_box",
+    "is_visible",
+    # Screenshots
+    "screenshot",
+    "screenshot_element",
+    # JavaScript
+    "evaluate",
+    "evaluate_on_node",
+    # Waiting
+    "wait_for_selector",
+    "wait_for_event",
+]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+async def _get_document_node(conn: CDPConnection) -> dom.NodeId:
+    """Return the root document NodeId."""
+    document = await conn.execute(dom.get_document(depth=0))
+    return document.node_id
+
+
+async def _resolve_node_center(
+    conn: CDPConnection, node_id: dom.NodeId
+) -> typing.Tuple[float, float]:
+    """Return the (x, y) centre of a DOM node's bounding box."""
+    box = await conn.execute(dom.get_box_model(node_id=node_id))
+    content = box.content  # Quad – flat list of 8 floats: x0,y0 x1,y1 x2,y2 x3,y3
+    xs = content[0::2]
+    ys = content[1::2]
+    cx = sum(xs) / len(xs)
+    cy = sum(ys) / len(ys)
+    return cx, cy
+
+
+# ---------------------------------------------------------------------------
+# Navigation
+# ---------------------------------------------------------------------------
+
+async def navigate(conn: CDPConnection, url: str, timeout: float = 30.0) -> page.FrameId:
+    """Navigate the current page to *url*.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param url: Destination URL.
+    :param timeout: Maximum seconds to wait for the navigation command.
+    :returns: The :class:`~cdp.page.FrameId` of the navigated frame.
+    :raises cdp.connection.CDPCommandError: If navigation fails.
+    """
+    result = await conn.execute(page.navigate(url=url), timeout=timeout)
+    frame_id: page.FrameId = result[0]
+    return frame_id
+
+
+async def reload(conn: CDPConnection, ignore_cache: bool = False) -> None:
+    """Reload the current page.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param ignore_cache: When ``True`` bypass the browser cache (hard reload).
+    """
+    await conn.execute(page.reload(ignore_cache=ignore_cache))
+
+
+async def go_back(conn: CDPConnection) -> bool:
+    """Navigate back in history.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :returns: ``True`` if a back entry existed, ``False`` otherwise.
+    """
+    index, entries = await conn.execute(page.get_navigation_history())
+    if index > 0:
+        entry = entries[index - 1]
+        await conn.execute(page.navigate_to_history_entry(entry_id=entry.id_))
+        return True
+    return False
+
+
+async def go_forward(conn: CDPConnection) -> bool:
+    """Navigate forward in history.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :returns: ``True`` if a forward entry existed, ``False`` otherwise.
+    """
+    index, entries = await conn.execute(page.get_navigation_history())
+    if index < len(entries) - 1:
+        entry = entries[index + 1]
+        await conn.execute(page.navigate_to_history_entry(entry_id=entry.id_))
+        return True
+    return False
+
+
+async def wait_for_load(
+    conn: CDPConnection,
+    timeout: float = 30.0,
+) -> None:
+    """Wait until the page fires a ``Page.loadEventFired`` event.
+
+    You must have called ``await conn.execute(page.enable())`` before using
+    this helper so that page events are delivered.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param timeout: Maximum seconds to wait.
+    :raises asyncio.TimeoutError: If the page does not load within *timeout*.
+    """
+    await wait_for_event(conn, page.LoadEventFired, timeout=timeout)
+
+
+# ---------------------------------------------------------------------------
+# Element selection
+# ---------------------------------------------------------------------------
+
+async def query_selector(
+    conn: CDPConnection,
+    selector: str,
+    root: typing.Optional[dom.NodeId] = None,
+) -> dom.NodeId:
+    """Return the :class:`~cdp.dom.NodeId` of the first element matching
+    *selector* within *root* (defaults to the document root).
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector: CSS selector string.
+    :param root: Optional root node; defaults to the document root.
+    :returns: Matched :class:`~cdp.dom.NodeId`.
+    :raises ValueError: If no element matches the selector.
+    """
+    if root is None:
+        root = await _get_document_node(conn)
+    node_id = await conn.execute(dom.query_selector(node_id=root, selector=selector))
+    if node_id == 0:
+        raise ValueError(f"No element found for selector: {selector!r}")
+    return node_id
+
+
+async def query_selector_all(
+    conn: CDPConnection,
+    selector: str,
+    root: typing.Optional[dom.NodeId] = None,
+) -> typing.List[dom.NodeId]:
+    """Return all :class:`~cdp.dom.NodeId` values matching *selector*.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector: CSS selector string.
+    :param root: Optional root node; defaults to the document root.
+    :returns: List of matched :class:`~cdp.dom.NodeId` values (may be empty).
+    """
+    if root is None:
+        root = await _get_document_node(conn)
+    return await conn.execute(dom.query_selector_all(node_id=root, selector=selector))
+
+
+# ---------------------------------------------------------------------------
+# Element interaction
+# ---------------------------------------------------------------------------
+
+async def click(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+    button: str = "left",
+    click_count: int = 1,
+) -> None:
+    """Click the element identified by *selector_or_node*.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    :param button: Mouse button – ``"left"``, ``"right"``, or ``"middle"``.
+    :param click_count: Number of clicks (use ``2`` for double-click).
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    # Scroll node into view first so coordinates are correct.
+    await conn.execute(dom.scroll_into_view_if_needed(node_id=node))
+    cx, cy = await _resolve_node_center(conn, node)
+    _btn = input_.MouseButton(button)
+    for event_type in ("mouseMoved", "mousePressed", "mouseReleased"):
+        await conn.execute(
+            input_.dispatch_mouse_event(
+                type_=event_type,
+                x=cx,
+                y=cy,
+                button=_btn,
+                click_count=click_count,
+            )
+        )
+
+
+async def double_click(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+) -> None:
+    """Double-click the element identified by *selector_or_node*.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    """
+    await click(conn, selector_or_node, button="left", click_count=2)
+
+
+async def hover(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+) -> None:
+    """Move the mouse pointer over the element identified by *selector_or_node*.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    await conn.execute(dom.scroll_into_view_if_needed(node_id=node))
+    cx, cy = await _resolve_node_center(conn, node)
+    await conn.execute(
+        input_.dispatch_mouse_event(type_="mouseMoved", x=cx, y=cy)
+    )
+
+
+async def type_text(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+    text: str,
+    delay: float = 0.0,
+) -> None:
+    """Focus the element and type *text* into it, character by character.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    :param text: Text to type.
+    :param delay: Optional delay in seconds between keystrokes.
+    """
+    await focus(conn, selector_or_node)
+    for char in text:
+        await conn.execute(
+            input_.dispatch_key_event(type_="keyDown", text=char, key=char)
+        )
+        await conn.execute(
+            input_.dispatch_key_event(type_="keyUp", text=char, key=char)
+        )
+        if delay > 0:
+            await asyncio.sleep(delay)
+
+
+async def clear_and_type(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+    text: str,
+    delay: float = 0.0,
+) -> None:
+    """Select all existing text in the element, then type *text*.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    :param text: Replacement text.
+    :param delay: Optional delay in seconds between keystrokes.
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    await focus(conn, node)
+    # Select all – platform-agnostic via JavaScript.
+    await conn.execute(
+        runtime.evaluate(expression="document.execCommand('selectAll', false, null)")
+    )
+    await type_text(conn, node, text, delay=delay)
+
+
+async def press_key(
+    conn: CDPConnection,
+    key: str,
+    modifiers: int = 0,
+) -> None:
+    """Simulate pressing a single keyboard key.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param key: DOM key name, e.g. ``"Enter"``, ``"Tab"``, ``"Escape"``,
+        ``"ArrowDown"``, or a single character like ``"a"``.
+    :param modifiers: Bit-field of modifier keys
+        (Alt=1, Ctrl=2, Meta=4, Shift=8).
+    """
+    for event_type in ("keyDown", "keyUp"):
+        await conn.execute(
+            input_.dispatch_key_event(
+                type_=event_type,
+                key=key,
+                modifiers=modifiers,
+            )
+        )
+
+
+async def focus(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+) -> None:
+    """Move keyboard focus to the element identified by *selector_or_node*.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    await conn.execute(dom.focus(node_id=node))
+
+
+async def select_option(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+    value: str,
+) -> None:
+    """Select the ``<option>`` with the given *value* inside a ``<select>`` element.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector for the ``<select>`` element.
+    :param value: The ``value`` attribute of the ``<option>`` to select.
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    obj = await conn.execute(dom.resolve_node(node_id=node))
+    if obj is None:
+        raise ValueError("Could not resolve node to a remote object")
+    escaped = value.replace("'", "\\'")
+    expr = f"function() {{ this.value = '{escaped}'; this.dispatchEvent(new Event('change', {{bubbles: true}})); }}"
+    await conn.execute(
+        runtime.call_function_on(
+            function_declaration=expr,
+            object_id=obj.object_id,
+        )
+    )
+
+
+# ---------------------------------------------------------------------------
+# Element inspection
+# ---------------------------------------------------------------------------
+
+async def get_text(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+) -> str:
+    """Return the ``innerText`` of the element.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    :returns: The ``innerText`` value (empty string if not available).
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    obj = await conn.execute(dom.resolve_node(node_id=node))
+    if obj is None or obj.object_id is None:
+        return ""
+    text_result, text_exc = await conn.execute(
+        runtime.call_function_on(
+            function_declaration="function() { return this.innerText || this.textContent || ''; }",
+            object_id=obj.object_id,
+        )
+    )
+    if text_exc is not None:
+        return ""
+    return str(text_result.value) if text_result and text_result.value is not None else ""
+
+
+async def get_attribute(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+    attribute: str,
+) -> typing.Optional[str]:
+    """Return the value of *attribute* on the element, or ``None`` if absent.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    :param attribute: Attribute name, e.g. ``"href"``, ``"class"``, ``"value"``.
+    :returns: Attribute value or ``None``.
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    attrs = await conn.execute(dom.get_attributes(node_id=node))
+    # attrs is a flat list: [name, value, name, value, ...]
+    it = iter(attrs)
+    mapping = dict(zip(it, it))
+    return mapping.get(attribute)
+
+
+async def get_bounding_box(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+) -> typing.Dict[str, float]:
+    """Return the bounding box of an element as a dict with keys
+    ``x``, ``y``, ``width``, ``height``.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    :returns: Dict with bounding-box information.
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    box = await conn.execute(dom.get_box_model(node_id=node))
+    content = box.content
+    xs = content[0::2]
+    ys = content[1::2]
+    return {
+        "x": min(xs),
+        "y": min(ys),
+        "width": max(xs) - min(xs),
+        "height": max(ys) - min(ys),
+    }
+
+
+async def is_visible(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+) -> bool:
+    """Return ``True`` if the element is visible on screen.
+
+    Visibility is determined by checking that the element's bounding box has
+    a non-zero area and that the CSS ``visibility`` / ``display`` properties
+    do not hide it.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    try:
+        box = await conn.execute(dom.get_box_model(node_id=node))
+    except Exception:
+        return False
+    content = box.content
+    xs = content[0::2]
+    ys = content[1::2]
+    width = max(xs) - min(xs)
+    height = max(ys) - min(ys)
+    if width <= 0 or height <= 0:
+        return False
+    obj = await conn.execute(dom.resolve_node(node_id=node))
+    if obj is None or obj.object_id is None:
+        return False
+    vis_result, vis_exc = await conn.execute(
+        runtime.call_function_on(
+            function_declaration=(
+                "function() {"
+                "  var style = window.getComputedStyle(this);"
+                "  return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';"
+                "}"
+            ),
+            object_id=obj.object_id,
+        )
+    )
+    if vis_exc is not None:
+        return False
+    return bool(vis_result.value) if vis_result else False
+
+
+# ---------------------------------------------------------------------------
+# Screenshots
+# ---------------------------------------------------------------------------
+
+async def screenshot(
+    conn: CDPConnection,
+    format_: str = "png",
+    quality: typing.Optional[int] = None,
+    full_page: bool = False,
+) -> bytes:
+    """Capture a screenshot of the current viewport.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param format_: Image format – ``"png"`` (default) or ``"jpeg"``.
+    :param quality: JPEG quality ``0``–``100`` (ignored for PNG).
+    :param full_page: When ``True``, capture the full scrollable page.
+    :returns: Raw image data as :class:`bytes`.
+    """
+    data_b64: str = await conn.execute(
+        page.capture_screenshot(
+            format_=format_,
+            quality=quality,
+            capture_beyond_viewport=full_page,
+        )
+    )
+    return base64.b64decode(data_b64)
+
+
+async def screenshot_element(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+    format_: str = "png",
+    quality: typing.Optional[int] = None,
+) -> bytes:
+    """Capture a screenshot clipped to a specific element.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    :param format_: Image format – ``"png"`` (default) or ``"jpeg"``.
+    :param quality: JPEG quality ``0``–``100`` (ignored for PNG).
+    :returns: Raw image data as :class:`bytes`.
+    """
+    bbox = await get_bounding_box(conn, selector_or_node)
+    clip = page.Viewport(
+        x=bbox["x"],
+        y=bbox["y"],
+        width=bbox["width"],
+        height=bbox["height"],
+        scale=1.0,
+    )
+    data_b64: str = await conn.execute(
+        page.capture_screenshot(format_=format_, quality=quality, clip=clip)
+    )
+    return base64.b64decode(data_b64)
+
+
+# ---------------------------------------------------------------------------
+# JavaScript evaluation
+# ---------------------------------------------------------------------------
+
+async def evaluate(
+    conn: CDPConnection,
+    expression: str,
+    await_promise: bool = False,
+) -> typing.Any:
+    """Evaluate a JavaScript *expression* in the page context.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param expression: JavaScript expression to evaluate.
+    :param await_promise: When ``True``, await a returned Promise.
+    :returns: The primitive value returned by the expression, or ``None``.
+    :raises RuntimeError: If the expression throws a JavaScript exception.
+    """
+    result, exc = await conn.execute(
+        runtime.evaluate(expression=expression, await_promise=await_promise)
+    )
+    if exc is not None:
+        raise RuntimeError(
+            f"JavaScript exception: {exc.text}"
+        )
+    return result.value if result else None
+
+
+async def evaluate_on_node(
+    conn: CDPConnection,
+    selector_or_node: typing.Union[str, dom.NodeId],
+    function_declaration: str,
+) -> typing.Any:
+    """Call a JavaScript function with the matched element as ``this``.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector_or_node: CSS selector string or a :class:`~cdp.dom.NodeId`.
+    :param function_declaration: JavaScript function body, e.g.
+        ``"function() { return this.value; }"``.
+    :returns: The primitive return value, or ``None``.
+    :raises RuntimeError: If the function throws a JavaScript exception.
+    """
+    node = (
+        await query_selector(conn, selector_or_node)
+        if isinstance(selector_or_node, str)
+        else selector_or_node
+    )
+    obj = await conn.execute(dom.resolve_node(node_id=node))
+    if obj is None or obj.object_id is None:
+        raise ValueError("Could not resolve node to a remote object")
+    result, exc = await conn.execute(
+        runtime.call_function_on(
+            function_declaration=function_declaration,
+            object_id=obj.object_id,
+        )
+    )
+    if exc is not None:
+        raise RuntimeError(f"JavaScript exception: {exc.text}")
+    return result.value if result else None
+
+
+# ---------------------------------------------------------------------------
+# Waiting
+# ---------------------------------------------------------------------------
+
+async def wait_for_selector(
+    conn: CDPConnection,
+    selector: str,
+    timeout: float = 30.0,
+    poll_interval: float = 0.25,
+    root: typing.Optional[dom.NodeId] = None,
+) -> dom.NodeId:
+    """Poll until *selector* matches an element in the DOM.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param selector: CSS selector string.
+    :param timeout: Maximum seconds to wait.
+    :param poll_interval: Polling interval in seconds.
+    :param root: Optional root node; defaults to the document root.
+    :returns: The matched :class:`~cdp.dom.NodeId`.
+    :raises asyncio.TimeoutError: If no element appears within *timeout*.
+    """
+    deadline = asyncio.get_event_loop().time() + timeout
+    while True:
+        try:
+            node_id = await query_selector(conn, selector, root=root)
+            return node_id
+        except ValueError:
+            pass
+        if asyncio.get_event_loop().time() >= deadline:
+            raise asyncio.TimeoutError(
+                f"Timed out waiting for selector {selector!r} ({timeout}s)"
+            )
+        await asyncio.sleep(poll_interval)
+
+
+_T_Event = typing.TypeVar("_T_Event")
+
+
+async def wait_for_event(
+    conn: CDPConnection,
+    event_type: typing.Type[_T_Event],
+    timeout: float = 30.0,
+) -> _T_Event:
+    """Wait for a specific CDP event type to be received.
+
+    :param conn: An open :class:`~cdp.connection.CDPConnection`.
+    :param event_type: The CDP event class to wait for, e.g.
+        :class:`~cdp.page.LoadEventFired`.
+    :param timeout: Maximum seconds to wait.
+    :returns: The received event instance.
+    :raises asyncio.TimeoutError: If the event is not received within *timeout*.
+    """
+    async def _wait() -> _T_Event:
+        async for event in conn.listen():
+            if isinstance(event, event_type):
+                return event  # type: ignore[return-value]
+        raise CDPConnectionError("Connection closed before event arrived")  # noqa: F821
+
+    try:
+        from cdp.connection import CDPConnectionError  # local import to avoid circular
+        return await asyncio.wait_for(_wait(), timeout=timeout)
+    except asyncio.TimeoutError:
+        raise asyncio.TimeoutError(
+            f"Timed out waiting for event {event_type.__name__} ({timeout}s)"
+        )
diff --git a/docs/browser_control.rst b/docs/browser_control.rst
new file mode 100644
index 0000000..7bc70ee
--- /dev/null
+++ b/docs/browser_control.rst
@@ -0,0 +1,199 @@
+Browser Control
+===============
+
+The ``cdp.browser_control`` module provides a high-level browser automation
+API built on top of the raw CDP domain modules and
+:class:`~cdp.connection.CDPConnection`.  It offers a set of coroutines
+similar to what Playwright or Puppeteer expose, without requiring an external
+automation framework.
+
+.. note::
+
+   This module requires the ``websockets`` dependency.  Install it with::
+
+       pip install chrome-devtools-protocol[io]
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+Quick Start
+-----------
+
+.. code-block:: python
+
+   import asyncio
+   from cdp.connection import CDPConnection
+   from cdp import browser_control as bc
+   from cdp import page
+
+   async def main():
+       async with CDPConnection("ws://localhost:9222/devtools/page/ID") as conn:
+           # Enable page events (required for wait_for_load)
+           await conn.execute(page.enable())
+
+           # Navigate and wait for the page to load
+           await bc.navigate(conn, "https://example.com")
+           await bc.wait_for_load(conn)
+
+           # Read the heading text
+           text = await bc.get_text(conn, "h1")
+           print(f"Heading: {text}")
+
+           # Click a link
+           await bc.click(conn, "a")
+
+           # Fill a form
+           await bc.clear_and_type(conn, "input[name='q']", "hello world")
+           await bc.press_key(conn, "Enter")
+
+           # Capture a screenshot
+           png_bytes = await bc.screenshot(conn)
+           with open("page.png", "wb") as f:
+               f.write(png_bytes)
+
+   asyncio.run(main())
+
+
+Navigation
+----------
+
+.. autofunction:: cdp.browser_control.navigate
+.. autofunction:: cdp.browser_control.reload
+.. autofunction:: cdp.browser_control.go_back
+.. autofunction:: cdp.browser_control.go_forward
+.. autofunction:: cdp.browser_control.wait_for_load
+
+
+Element Selection
+-----------------
+
+.. autofunction:: cdp.browser_control.query_selector
+.. autofunction:: cdp.browser_control.query_selector_all
+
+
+Element Interaction
+-------------------
+
+.. autofunction:: cdp.browser_control.click
+.. autofunction:: cdp.browser_control.double_click
+.. autofunction:: cdp.browser_control.hover
+.. autofunction:: cdp.browser_control.type_text
+.. autofunction:: cdp.browser_control.clear_and_type
+.. autofunction:: cdp.browser_control.press_key
+.. autofunction:: cdp.browser_control.focus
+.. autofunction:: cdp.browser_control.select_option
+
+
+Element Inspection
+------------------
+
+.. autofunction:: cdp.browser_control.get_text
+.. autofunction:: cdp.browser_control.get_attribute
+.. autofunction:: cdp.browser_control.get_bounding_box
+.. autofunction:: cdp.browser_control.is_visible
+
+
+Screenshots
+-----------
+
+.. autofunction:: cdp.browser_control.screenshot
+.. autofunction:: cdp.browser_control.screenshot_element
+
+
+JavaScript
+----------
+
+.. autofunction:: cdp.browser_control.evaluate
+.. autofunction:: cdp.browser_control.evaluate_on_node
+
+
+Waiting
+-------
+
+.. autofunction:: cdp.browser_control.wait_for_selector
+.. autofunction:: cdp.browser_control.wait_for_event
+
+
+Patterns and Recipes
+--------------------
+
+Waiting for an element before interacting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   node = await bc.wait_for_selector(conn, "#submit-button", timeout=10)
+   await bc.click(conn, node)
+
+
+Checking visibility before clicking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   if await bc.is_visible(conn, ".cookie-banner"):
+       await bc.click(conn, ".cookie-banner .dismiss")
+
+
+Reading all list items
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   items = await bc.query_selector_all(conn, "ul.results li")
+   for node in items:
+       text = await bc.get_text(conn, node)
+       print(text)
+
+
+Extracting a link href
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   href = await bc.get_attribute(conn, "a.download", "href")
+
+
+Selecting a dropdown value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   await bc.select_option(conn, "select#country", "US")
+
+
+Keyboard shortcuts
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   # Ctrl+A then Delete
+   await bc.press_key(conn, "a", modifiers=2)   # Ctrl=2
+   await bc.press_key(conn, "Delete")
+
+
+Capturing a single element screenshot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   png = await bc.screenshot_element(conn, "#logo")
+   with open("logo.png", "wb") as f:
+       f.write(png)
+
+
+Running arbitrary JavaScript
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   count = await bc.evaluate(conn, "document.querySelectorAll('li').length")
+   print(f"Found {count} list items")
+
+   # Operate on a specific element
+   checked = await bc.evaluate_on_node(
+       conn, "input[type='checkbox']",
+       "function() { return this.checked; }"
+   )
diff --git a/docs/index.rst b/docs/index.rst
index c4ba5e6..11d5d94 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,7 @@ Python wrappers for Chrome DevTools Protocol (CDP).
 
    overview
    getting_started
+   browser_control
    api
    develop
    changelog
diff --git a/docs/overview.rst b/docs/overview.rst
index eeacb11..5ace8f4 100644
--- a/docs/overview.rst
+++ b/docs/overview.rst
@@ -16,12 +16,19 @@ not catch any typos in your JSON objects, and you wouldn't get autocomplete for
 any parts of the JSON data structure. By providing a set of native Python
 wrappers, this project makes it easier and faster to write CDP client code.
 
-**This library does not perform any I/O!** In order to maximize
-flexibility, this library does not actually handle any network I/O, such as
-opening a socket or negotiating a WebSocket protocol. Instead, that
-responsibility is left to higher-level libraries, for example
-`trio-chrome-devtools-protocol
-<https://github.com/hyperiongray/trio-chrome-devtools-protocol>`_.
+**Two usage modes are available:**
+
+* **Sans-I/O mode (original):** The core library provides type wrappers without
+  performing any I/O. This maximises flexibility and allows integration with any
+  async framework such as
+  `trio-chrome-devtools-protocol
+  <https://github.com/hyperiongray/trio-chrome-devtools-protocol>`_.
+
+* **I/O mode:** The ``cdp.connection`` module handles the WebSocket lifecycle,
+  JSON-RPC message framing, and command multiplexing.  The
+  ``cdp.browser_control`` module layers a high-level automation API on top of
+  this, providing Playwright-style helpers for navigation, element interaction,
+  screenshots, and more.  See :doc:`browser_control` for details.
 
 **This package provides Chrome DevTools Protocol r678025.** Download a compatible
 Chrome package:
@@ -31,13 +38,14 @@ Chrome package:
 * `Windows 32-bit <https://storage.googleapis.com/chromium-browser-snapshots/Win/678025/chrome-win.zip>`_
 * `Windows 64-bit <https://storage.googleapis.com/chromium-browser-snapshots/Win_x64/678025/chrome-win.zip>`_
 
-**Install from PyPI (requires Python ≥3.7):**
+**Install from PyPI (requires Python ≥3.8):**
 
 ::
 
-    $ pip install chrome-devtools-protocol
+    $ pip install chrome-devtools-protocol        # Sans-I/O only
+    $ pip install chrome-devtools-protocol[io]    # With WebSocket / browser-control support
 
-**Sample code:**
+**Quick example (Sans-I/O mode):**
 
 .. code-block:: python
 
@@ -45,3 +53,21 @@ Chrome package:
 
     frame_id = page.FrameId('my id')
     assert repr(frame_id) == "FrameId('my id')"
+
+**Quick example (browser control):**
+
+.. code-block:: python
+
+    import asyncio
+    from cdp.connection import CDPConnection
+    from cdp import browser_control as bc
+    from cdp import page
+
+    async def main():
+        async with CDPConnection("ws://localhost:9222/devtools/page/ID") as conn:
+            await conn.execute(page.enable())
+            await bc.navigate(conn, "https://example.com")
+            await bc.wait_for_load(conn)
+            print(await bc.get_text(conn, "h1"))
+
+    asyncio.run(main())
diff --git a/examples/browser_control_example.py b/examples/browser_control_example.py
new file mode 100644
index 0000000..9e407af
--- /dev/null
+++ b/examples/browser_control_example.py
@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Browser Control Example
+
+Demonstrates the cdp.browser_control high-level automation API.
+
+Prerequisites:
+    pip install chrome-devtools-protocol[io]
+
+Start Chrome with remote debugging enabled:
+    chrome --remote-debugging-port=9222 --headless
+
+Then run:
+    python examples/browser_control_example.py
+"""
+
+import asyncio
+from cdp.connection import CDPConnection
+from cdp import browser_control as bc
+from cdp import page
+
+
+# Replace with a real CDP WebSocket URL from chrome://inspect or the
+# JSON endpoint at http://localhost:9222/json
+CDP_URL = "ws://localhost:9222/devtools/page/YOUR_PAGE_ID"
+
+
+async def demo_navigation(conn: CDPConnection) -> None:
+    """Navigate to a URL and wait for the page to load."""
+    print("\n--- Navigation ---")
+    await conn.execute(page.enable())
+    frame_id = await bc.navigate(conn, "https://example.com")
+    await bc.wait_for_load(conn)
+    print(f"Navigated, frame_id={frame_id}")
+
+
+async def demo_element_selection(conn: CDPConnection) -> None:
+    """Query DOM elements with CSS selectors."""
+    print("\n--- Element Selection ---")
+    h1 = await bc.query_selector(conn, "h1")
+    print(f"Found <h1> node: {h1!r}")
+
+    all_links = await bc.query_selector_all(conn, "a")
+    print(f"Found {len(all_links)} link(s)")
+
+
+async def demo_text_and_attributes(conn: CDPConnection) -> None:
+    """Read text content and attributes from elements."""
+    print("\n--- Text & Attributes ---")
+    text = await bc.get_text(conn, "h1")
+    print(f"<h1> text: {text!r}")
+
+    href = await bc.get_attribute(conn, "a", "href")
+    print(f"First link href: {href!r}")
+
+    bbox = await bc.get_bounding_box(conn, "h1")
+    print(f"<h1> bounding box: {bbox}")
+
+    visible = await bc.is_visible(conn, "h1")
+    print(f"<h1> visible: {visible}")
+
+
+async def demo_interaction(conn: CDPConnection) -> None:
+    """Click elements and type into inputs."""
+    print("\n--- Interaction ---")
+    # Navigate to a page with a search form
+    await conn.execute(page.enable())
+    await bc.navigate(conn, "https://www.google.com")
+    await bc.wait_for_load(conn)
+
+    search_box = await bc.wait_for_selector(conn, "textarea[name='q']", timeout=10)
+    await bc.click(conn, search_box)
+    await bc.type_text(conn, search_box, "Python CDP", delay=0.05)
+    await bc.press_key(conn, "Enter")
+    print("Submitted search form")
+
+
+async def demo_javascript(conn: CDPConnection) -> None:
+    """Evaluate JavaScript in the page context."""
+    print("\n--- JavaScript ---")
+    title = await bc.evaluate(conn, "document.title")
+    print(f"Page title via JS: {title!r}")
+
+    link_count = await bc.evaluate(conn, "document.querySelectorAll('a').length")
+    print(f"Link count via JS: {link_count}")
+
+
+async def demo_screenshot(conn: CDPConnection) -> None:
+    """Take screenshots of the full page and a specific element."""
+    print("\n--- Screenshots ---")
+    png = await bc.screenshot(conn)
+    with open("/tmp/page.png", "wb") as fh:
+        fh.write(png)
+    print(f"Full-page screenshot saved ({len(png)} bytes) → /tmp/page.png")
+
+    try:
+        png_elem = await bc.screenshot_element(conn, "h1")
+        with open("/tmp/h1.png", "wb") as fh:
+            fh.write(png_elem)
+        print(f"Element screenshot saved ({len(png_elem)} bytes) → /tmp/h1.png")
+    except Exception as exc:
+        print(f"Element screenshot skipped: {exc}")
+
+
+async def main() -> None:
+    print("CDP Browser Control Examples")
+    print("=" * 50)
+    print(f"Connecting to {CDP_URL}")
+
+    async with CDPConnection(CDP_URL) as conn:
+        await demo_navigation(conn)
+        await demo_element_selection(conn)
+        await demo_text_and_attributes(conn)
+        await demo_javascript(conn)
+        await demo_screenshot(conn)
+        # await demo_interaction(conn)  # Uncomment to test form interaction
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/test/test_browser_control.py b/test/test_browser_control.py
new file mode 100644
index 0000000..40a40d0
--- /dev/null
+++ b/test/test_browser_control.py
@@ -0,0 +1,452 @@
+"""
+Tests for cdp.browser_control module.
+
+These tests mock CDPConnection so no real browser is needed.
+"""
+import asyncio
+import json
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch, call
+
+from cdp import dom, page, runtime
+from cdp.browser_control import (
+    navigate,
+    reload,
+    go_back,
+    go_forward,
+    query_selector,
+    query_selector_all,
+    click,
+    double_click,
+    hover,
+    type_text,
+    clear_and_type,
+    press_key,
+    focus,
+    get_text,
+    get_attribute,
+    get_bounding_box,
+    is_visible,
+    screenshot,
+    screenshot_element,
+    evaluate,
+    evaluate_on_node,
+    wait_for_selector,
+    wait_for_event,
+)
+
+
+# ---------------------------------------------------------------------------
+# Mock helpers
+# ---------------------------------------------------------------------------
+
+def _make_conn(*side_effects):
+    """Build a mock CDPConnection whose execute() returns values in order."""
+    conn = MagicMock()
+    conn.execute = AsyncMock(side_effect=list(side_effects))
+    # listen() is an async generator – mock it properly when needed per test.
+    return conn
+
+
+# ---------------------------------------------------------------------------
+# Navigation tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_navigate_returns_frame_id():
+    frame_id = page.FrameId("frame-1")
+    conn = _make_conn((frame_id, None, None, None))
+    result = await navigate(conn, "https://example.com")
+    assert result == frame_id
+    conn.execute.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_reload_calls_page_reload():
+    conn = _make_conn(None)
+    await reload(conn)
+    conn.execute.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_go_back_when_history_available():
+    entry = page.NavigationEntry(
+        id_=1,
+        url="https://prev.com",
+        user_typed_url="https://prev.com",
+        title="Prev",
+        transition_type=page.TransitionType.TYPED,
+    )
+    # get_navigation_history returns (index, entries)
+    conn = _make_conn((1, [entry, MagicMock()]), None)
+    result = await go_back(conn)
+    assert result is True
+    assert conn.execute.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_go_back_at_start_of_history():
+    conn = _make_conn((0, [MagicMock()]))
+    result = await go_back(conn)
+    assert result is False
+    conn.execute.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_go_forward_when_history_available():
+    entry_next = page.NavigationEntry(
+        id_=2,
+        url="https://next.com",
+        user_typed_url="https://next.com",
+        title="Next",
+        transition_type=page.TransitionType.TYPED,
+    )
+    conn = _make_conn((0, [MagicMock(), entry_next]), None)
+    result = await go_forward(conn)
+    assert result is True
+    assert conn.execute.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_go_forward_at_end_of_history():
+    conn = _make_conn((1, [MagicMock(), MagicMock()]))
+    result = await go_forward(conn)
+    assert result is False
+    conn.execute.assert_awaited_once()
+
+
+# ---------------------------------------------------------------------------
+# Element selection tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_query_selector_found():
+    doc_node = dom.Node(
+        node_id=dom.NodeId(1),
+        backend_node_id=dom.BackendNodeId(1),
+        node_type=9,
+        node_name="#document",
+        local_name="",
+        node_value="",
+    )
+    target_node_id = dom.NodeId(42)
+    conn = _make_conn(doc_node, target_node_id)
+    result = await query_selector(conn, "h1")
+    assert result == target_node_id
+
+
+@pytest.mark.asyncio
+async def test_query_selector_not_found_raises():
+    doc_node = dom.Node(
+        node_id=dom.NodeId(1),
+        backend_node_id=dom.BackendNodeId(1),
+        node_type=9,
+        node_name="#document",
+        local_name="",
+        node_value="",
+    )
+    conn = _make_conn(doc_node, dom.NodeId(0))
+    with pytest.raises(ValueError, match="No element found"):
+        await query_selector(conn, ".missing")
+
+
+@pytest.mark.asyncio
+async def test_query_selector_all():
+    doc_node = dom.Node(
+        node_id=dom.NodeId(1),
+        backend_node_id=dom.BackendNodeId(1),
+        node_type=9,
+        node_name="#document",
+        local_name="",
+        node_value="",
+    )
+    ids = [dom.NodeId(10), dom.NodeId(20)]
+    conn = _make_conn(doc_node, ids)
+    result = await query_selector_all(conn, "li")
+    assert result == ids
+
+
+@pytest.mark.asyncio
+async def test_query_selector_with_explicit_root():
+    """When a root NodeId is provided, get_document should NOT be called."""
+    root = dom.NodeId(5)
+    target = dom.NodeId(99)
+    conn = _make_conn(target)
+    result = await query_selector(conn, "span", root=root)
+    assert result == target
+    # Only one execute call: query_selector itself
+    conn.execute.assert_awaited_once()
+
+
+# ---------------------------------------------------------------------------
+# Element interaction tests
+# ---------------------------------------------------------------------------
+
+def _make_box_model(x=10.0, y=20.0, w=100.0, h=50.0):
+    """Create a minimal BoxModel whose content quad covers the given rect."""
+    # Quad is [x0,y0, x1,y1, x2,y2, x3,y3] clockwise from top-left.
+    quad = dom.Quad([x, y, x + w, y, x + w, y + h, x, y + h])
+    return dom.BoxModel(
+        content=quad,
+        padding=quad,
+        border=quad,
+        margin=quad,
+        width=int(w),
+        height=int(h),
+    )
+
+
+@pytest.mark.asyncio
+async def test_click_dispatches_mouse_events():
+    doc_node = dom.Node(
+        node_id=dom.NodeId(1),
+        backend_node_id=dom.BackendNodeId(1),
+        node_type=9,
+        node_name="#document",
+        local_name="",
+        node_value="",
+    )
+    target_node = dom.NodeId(42)
+    box = _make_box_model(10, 20, 100, 50)
+    # Calls: get_document, query_selector, scroll_into_view, get_box_model,
+    # dispatch_mouse_event x3
+    conn = _make_conn(doc_node, target_node, None, box, None, None, None)
+    await click(conn, "button")
+    assert conn.execute.await_count == 7
+
+
+@pytest.mark.asyncio
+async def test_click_with_node_id_skips_selector():
+    node = dom.NodeId(42)
+    box = _make_box_model()
+    # Calls: scroll_into_view, get_box_model, dispatch_mouse_event x3
+    conn = _make_conn(None, box, None, None, None)
+    await click(conn, node)
+    assert conn.execute.await_count == 5
+
+
+@pytest.mark.asyncio
+async def test_hover_dispatches_mousemoved():
+    node = dom.NodeId(7)
+    box = _make_box_model()
+    conn = _make_conn(None, box, None)
+    await hover(conn, node)
+    assert conn.execute.await_count == 3
+
+
+@pytest.mark.asyncio
+async def test_press_key_sends_keydown_and_keyup():
+    conn = _make_conn(None, None)
+    await press_key(conn, "Enter")
+    assert conn.execute.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_type_text_sends_events_per_character():
+    doc_node = dom.Node(
+        node_id=dom.NodeId(1),
+        backend_node_id=dom.BackendNodeId(1),
+        node_type=9,
+        node_name="#document",
+        local_name="",
+        node_value="",
+    )
+    target_node = dom.NodeId(5)
+    text = "hi"
+    # focus: get_document, query_selector, dom.focus
+    # then 2 chars * 2 events = 4
+    conn = _make_conn(doc_node, target_node, None, None, None, None, None)
+    await type_text(conn, "input", text)
+    # 3 (focus) + 4 (2 chars * 2 key events) = 7
+    assert conn.execute.await_count == 7
+
+
+# ---------------------------------------------------------------------------
+# Element inspection tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_get_attribute_returns_value():
+    doc_node = dom.Node(
+        node_id=dom.NodeId(1),
+        backend_node_id=dom.BackendNodeId(1),
+        node_type=9,
+        node_name="#document",
+        local_name="",
+        node_value="",
+    )
+    target_node = dom.NodeId(10)
+    attrs = ["class", "hero", "href", "https://example.com"]
+    conn = _make_conn(doc_node, target_node, attrs)
+    result = await get_attribute(conn, "a", "href")
+    assert result == "https://example.com"
+
+
+@pytest.mark.asyncio
+async def test_get_attribute_missing_returns_none():
+    node = dom.NodeId(10)
+    attrs = ["class", "hero"]
+    conn = _make_conn(attrs)
+    result = await get_attribute(conn, node, "href")
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_get_bounding_box():
+    node = dom.NodeId(3)
+    box = _make_box_model(x=5.0, y=10.0, w=200.0, h=80.0)
+    conn = _make_conn(box)
+    result = await get_bounding_box(conn, node)
+    assert result["x"] == pytest.approx(5.0)
+    assert result["y"] == pytest.approx(10.0)
+    assert result["width"] == pytest.approx(200.0)
+    assert result["height"] == pytest.approx(80.0)
+
+
+@pytest.mark.asyncio
+async def test_get_text_returns_inner_text():
+    node = dom.NodeId(7)
+    remote_obj = runtime.RemoteObject(type_="string", value="Hello World")
+    remote_obj.object_id = runtime.RemoteObjectId("obj-1")
+    text_remote = runtime.RemoteObject(type_="string", value="Hello World")
+    conn = _make_conn(remote_obj, (text_remote, None))
+    result = await get_text(conn, node)
+    assert result == "Hello World"
+
+
+# ---------------------------------------------------------------------------
+# Screenshot tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_screenshot_decodes_base64():
+    import base64
+    raw = b"\x89PNG\r\n\x1a\n"  # fake PNG header
+    b64 = base64.b64encode(raw).decode()
+    conn = _make_conn(b64)
+    result = await screenshot(conn)
+    assert result == raw
+
+
+@pytest.mark.asyncio
+async def test_screenshot_element():
+    import base64
+    node = dom.NodeId(5)
+    box = _make_box_model(x=0, y=0, w=100, h=50)
+    raw = b"jpeg_data"
+    b64 = base64.b64encode(raw).decode()
+    conn = _make_conn(box, b64)
+    result = await screenshot_element(conn, node, format_="jpeg")
+    assert result == raw
+    assert conn.execute.await_count == 2
+
+
+# ---------------------------------------------------------------------------
+# JavaScript evaluation tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_evaluate_returns_value():
+    remote = runtime.RemoteObject(type_="number", value=42)
+    conn = _make_conn((remote, None))
+    result = await evaluate(conn, "1+1")
+    assert result == 42
+
+
+@pytest.mark.asyncio
+async def test_evaluate_raises_on_exception():
+    exc_details = runtime.ExceptionDetails(
+        exception_id=1,
+        text="SyntaxError",
+        line_number=0,
+        column_number=0,
+    )
+    conn = _make_conn((None, exc_details))
+    with pytest.raises(RuntimeError, match="JavaScript exception"):
+        await evaluate(conn, "throw new Error()")
+
+
+@pytest.mark.asyncio
+async def test_evaluate_on_node():
+    node = dom.NodeId(9)
+    remote_obj = runtime.RemoteObject(type_="object")
+    remote_obj.object_id = runtime.RemoteObjectId("obj-2")
+    text_remote = runtime.RemoteObject(type_="string", value="inner")
+    conn = _make_conn(remote_obj, (text_remote, None))
+    result = await evaluate_on_node(conn, node, "function() { return this.value; }")
+    assert result == "inner"
+
+
+# ---------------------------------------------------------------------------
+# wait_for_selector tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_wait_for_selector_found_immediately():
+    doc_node = dom.Node(
+        node_id=dom.NodeId(1),
+        backend_node_id=dom.BackendNodeId(1),
+        node_type=9,
+        node_name="#document",
+        local_name="",
+        node_value="",
+    )
+    target = dom.NodeId(55)
+    conn = _make_conn(doc_node, target)
+    result = await wait_for_selector(conn, "h2")
+    assert result == target
+
+
+@pytest.mark.asyncio
+async def test_wait_for_selector_timeout():
+    doc_node = dom.Node(
+        node_id=dom.NodeId(1),
+        backend_node_id=dom.BackendNodeId(1),
+        node_type=9,
+        node_name="#document",
+        local_name="",
+        node_value="",
+    )
+    # Always return NodeId(0) = not found
+    conn = MagicMock()
+    conn.execute = AsyncMock(side_effect=[doc_node, dom.NodeId(0)] * 20)
+    with pytest.raises(asyncio.TimeoutError):
+        await wait_for_selector(conn, ".ghost", timeout=0.1, poll_interval=0.05)
+
+
+# ---------------------------------------------------------------------------
+# wait_for_event tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_wait_for_event_receives_correct_type():
+    """wait_for_event should return the first matching event."""
+    target_event = page.LoadEventFired(timestamp=123.0)
+    other_event = page.FrameStoppedLoading(frame_id=page.FrameId("f1"))
+
+    async def _fake_listen():
+        yield other_event
+        yield target_event
+
+    conn = MagicMock()
+    conn.listen = _fake_listen
+    conn._closed = False
+
+    result = await wait_for_event(conn, page.LoadEventFired, timeout=2.0)
+    assert isinstance(result, page.LoadEventFired)
+    assert result.timestamp == 123.0
+
+
+@pytest.mark.asyncio
+async def test_wait_for_event_timeout():
+    async def _never_match():
+        for _ in range(100):
+            yield page.FrameStoppedLoading(frame_id=page.FrameId("f1"))
+            await asyncio.sleep(0.02)
+
+    conn = MagicMock()
+    conn.listen = _never_match
+    conn._closed = False
+
+    with pytest.raises(asyncio.TimeoutError):
+        await wait_for_event(conn, page.LoadEventFired, timeout=0.1)

From 2168c877b915215efff85d77465bf9f150703e49 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 8 Apr 2026 11:11:10 +0000
Subject: [PATCH 3/3] Address code review: fix CDPConnectionError import, JS
 escaping, execCommand replacement, test clarity

Agent-Logs-Url: https://github.com/HyperionGray/python-chrome-devtools-protocol/sessions/f5aedfd0-e970-4dc1-bc96-e614a946247f

Co-authored-by: P4X-ng <223870169+P4X-ng@users.noreply.github.com>
---
 cdp/browser_control.py              | 37 ++++++++++++++++++++++-------
 examples/browser_control_example.py |  9 ++++---
 test/test_browser_control.py        |  5 ++--
 3 files changed, 37 insertions(+), 14 deletions(-)

diff --git a/cdp/browser_control.py b/cdp/browser_control.py
index 149ebf2..fe9ba7d 100644
--- a/cdp/browser_control.py
+++ b/cdp/browser_control.py
@@ -37,10 +37,11 @@ async def main():
 
 import asyncio
 import base64
+import json as _json
 import typing
 
 from cdp import dom, input_, page, runtime
-from cdp.connection import CDPConnection
+from cdp.connection import CDPConnection, CDPConnectionError
 
 __all__ = [
     # Navigation
@@ -330,10 +331,28 @@ async def clear_and_type(
         else selector_or_node
     )
     await focus(conn, node)
-    # Select all – platform-agnostic via JavaScript.
-    await conn.execute(
-        runtime.evaluate(expression="document.execCommand('selectAll', false, null)")
-    )
+    # Select all existing content using the modern Selection/input API.
+    # For input/textarea: element.select(); for contenteditable: window.getSelection().
+    obj = await conn.execute(dom.resolve_node(node_id=node))
+    if obj and obj.object_id:
+        await conn.execute(
+            runtime.call_function_on(
+                function_declaration=(
+                    "function() {"
+                    "  if (typeof this.select === 'function') {"
+                    "    this.select();"
+                    "  } else {"
+                    "    var range = document.createRange();"
+                    "    range.selectNodeContents(this);"
+                    "    var sel = window.getSelection();"
+                    "    sel.removeAllRanges();"
+                    "    sel.addRange(range);"
+                    "  }"
+                    "}"
+                ),
+                object_id=obj.object_id,
+            )
+        )
     await type_text(conn, node, text, delay=delay)
 
 
@@ -396,8 +415,9 @@ async def select_option(
     obj = await conn.execute(dom.resolve_node(node_id=node))
     if obj is None:
         raise ValueError("Could not resolve node to a remote object")
-    escaped = value.replace("'", "\\'")
-    expr = f"function() {{ this.value = '{escaped}'; this.dispatchEvent(new Event('change', {{bubbles: true}})); }}"
+    # Use json.dumps to safely embed the value as a JS string literal.
+    js_value = _json.dumps(value)
+    expr = f"function() {{ this.value = {js_value}; this.dispatchEvent(new Event('change', {{bubbles: true}})); }}"
     await conn.execute(
         runtime.call_function_on(
             function_declaration=expr,
@@ -711,10 +731,9 @@ async def _wait() -> _T_Event:
         async for event in conn.listen():
             if isinstance(event, event_type):
                 return event  # type: ignore[return-value]
-        raise CDPConnectionError("Connection closed before event arrived")  # noqa: F821
+        raise CDPConnectionError("Connection closed before event arrived")
 
     try:
-        from cdp.connection import CDPConnectionError  # local import to avoid circular
         return await asyncio.wait_for(_wait(), timeout=timeout)
     except asyncio.TimeoutError:
         raise asyncio.TimeoutError(
diff --git a/examples/browser_control_example.py b/examples/browser_control_example.py
index 9e407af..0921486 100644
--- a/examples/browser_control_example.py
+++ b/examples/browser_control_example.py
@@ -10,7 +10,10 @@
 Start Chrome with remote debugging enabled:
     chrome --remote-debugging-port=9222 --headless
 
-Then run:
+Get the WebSocket URL for a tab:
+    curl http://localhost:9222/json
+
+Then update CDP_URL below with the "webSocketDebuggerUrl" value and run:
     python examples/browser_control_example.py
 """
 
@@ -20,8 +23,8 @@
 from cdp import page
 
 
-# Replace with a real CDP WebSocket URL from chrome://inspect or the
-# JSON endpoint at http://localhost:9222/json
+# Replace with the "webSocketDebuggerUrl" from http://localhost:9222/json
+# Example: "ws://localhost:9222/devtools/page/ABC123"
 CDP_URL = "ws://localhost:9222/devtools/page/YOUR_PAGE_ID"
 
 
diff --git a/test/test_browser_control.py b/test/test_browser_control.py
index 40a40d0..703b16e 100644
--- a/test/test_browser_control.py
+++ b/test/test_browser_control.py
@@ -407,9 +407,10 @@ async def test_wait_for_selector_timeout():
         local_name="",
         node_value="",
     )
-    # Always return NodeId(0) = not found
+    # Always return NodeId(0) = not found; repeat enough times for the timeout
+    _ENOUGH_ATTEMPTS = 20  # timeout=0.1s / poll_interval=0.05s → at most ~4 polls
     conn = MagicMock()
-    conn.execute = AsyncMock(side_effect=[doc_node, dom.NodeId(0)] * 20)
+    conn.execute = AsyncMock(side_effect=[doc_node, dom.NodeId(0)] * _ENOUGH_ATTEMPTS)
     with pytest.raises(asyncio.TimeoutError):
         await wait_for_selector(conn, ".ghost", timeout=0.1, poll_interval=0.05)