browserrig 0.1.0__py3-none-any.whl

browserrig/browser/frame.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, Sequence
+from contextlib import asynccontextmanager, suppress
+from dataclasses import dataclass, field
+from typing import Literal, overload
+
+from cdpify import CdpSession
+from cdpify.domains.page import FrameTree
+from cdpify.domains.runtime import CallArgument, RemoteObject
+from cdpify.exceptions import CDPCommandError
+from pydantic import BaseModel
+
+from browserrig.core import Bounds, BrowserError, FrameTransform
+from browserrig.scripts import OWNER_HITS, OwnerHitsArgs, Script, failure
+
+from .worlds import Worlds
+
+
+@dataclass(frozen=True, slots=True)
+class Frame:
+    """A CDP page frame: the top-level document or one embedded iframe.
+
+    Its isolated JavaScript world belongs to that frame, not to browser focus.
+    `transform` maps frame-local CSS pixels to the tab's viewport; `visible` is the
+    part of the frame left unclipped by its ancestors, in viewport pixels.
+    """
+
+    id: str
+    cdp: CdpSession
+    transform: FrameTransform = FrameTransform()
+    visible: Bounds | None = None
+    parent: Frame | None = None
+    owner_id: int | None = None
+    document_id: str = ""
+    worlds: Worlds = field(default_factory=Worlds, repr=False, compare=False)
+
+    @property
+    def local_visible(self) -> Bounds | None:
+        """The visible area in this frame's own CSS pixels, for in-page scripts."""
+        return (
+            self.transform.bounds_to_local(self.visible)
+            if self.visible is not None
+            else None
+        )
+
+    async def frame_tree(self) -> FrameTree:
+        result = await self.cdp.page.get_frame_tree()
+        return result.frame_tree
+
+    async def upload_files(self, backend_node_id: int, paths: list[str]) -> None:
+        try:
+            await self.cdp.dom.set_file_input_files(
+                files=paths, backend_node_id=backend_node_id
+            )
+        except CDPCommandError as error:
+            raise BrowserError("STALE_ELEMENT") from error
+
+    @overload
+    async def run_on_node[A: BaseModel, R](
+        self,
+        backend_node_id: int,
+        script: Script[A, R],
+        args: A | None = None,
+        *,
+        by_value: Literal[True] = True,
+        user_gesture: bool = False,
+    ) -> R: ...
+
+    @overload
+    async def run_on_node[A: BaseModel, R](
+        self,
+        backend_node_id: int,
+        script: Script[A, R],
+        args: A | None = None,
+        *,
+        by_value: Literal[False],
+        user_gesture: bool = False,
+    ) -> RemoteObject: ...
+
+    async def run_on_node[A: BaseModel, R](
+        self,
+        backend_node_id: int,
+        script: Script[A, R],
+        args: A | None = None,
+        *,
+        by_value: bool = True,
+        user_gesture: bool = False,
+    ) -> R | RemoteObject:
+        """Run with one of this frame's DOM nodes as `this`."""
+        return await self.run(
+            script,
+            args,
+            node=backend_node_id,
+            by_value=by_value,
+            user_gesture=user_gesture,
+        )
+
+    async def run_on_owner[A: BaseModel, R](
+        self, script: Script[A, R], args: A | None = None
+    ) -> R:
+        """Run with this frame's embedding element as `this`, using the same error policy."""
+        assert self.parent is not None and self.owner_id is not None
+        try:
+            return await self.parent.run_on_node(self.owner_id, script, args)
+        except BrowserError as error:
+            if str(error) == "STALE_ELEMENT":
+                raise BrowserError(
+                    "Element frame no longer exists; use refs from the next observation"
+                ) from error
+            raise
+
+    async def check_point(self, x: float, y: float) -> None:
+        """A child hit test cannot see blockers in ancestor documents."""
+        if not (await self.visible_points(((x, y),)))[0]:
+            raise BrowserError("ELEMENT_BLOCKED")
+
+    async def visible_points(
+        self, points: tuple[tuple[float, float], ...]
+    ) -> tuple[bool, ...]:
+        visible = [True] * len(points)
+        current = self
+        while current.parent is not None:
+            visible_area = current.visible
+            hits = await current.run_on_owner(
+                OWNER_HITS,
+                OwnerHitsArgs(
+                    points=tuple(
+                        current.parent.transform.to_local(x, y) for x, y in points
+                    )
+                ),
+            )
+            visible = [
+                before
+                and hit
+                and (visible_area is None or visible_area.contains(*point))
+                for before, hit, point in zip(visible, hits, points, strict=True)
+            ]
+            current = current.parent
+        return tuple(visible)
+
+    async def context(self) -> int:
+        return await self.worlds.context(self.cdp, self.id, self.document_id)
+
+    @overload
+    async def run[A: BaseModel, R](
+        self,
+        script: Script[A, R],
+        args: A | None = None,
+        *,
+        node: int | None = None,
+        objects: Sequence[str] = (),
+        by_value: Literal[True] = True,
+        user_gesture: bool = False,
+    ) -> R: ...
+
+    @overload
+    async def run[A: BaseModel, R](
+        self,
+        script: Script[A, R],
+        args: A | None = None,
+        *,
+        node: int | None = None,
+        objects: Sequence[str] = (),
+        by_value: Literal[False],
+        user_gesture: bool = False,
+    ) -> RemoteObject: ...
+
+    async def run[A: BaseModel, R](
+        self,
+        script: Script[A, R],
+        args: A | None = None,
+        *,
+        node: int | None = None,
+        objects: Sequence[str] = (),
+        by_value: bool = True,
+        user_gesture: bool = False,
+    ) -> R | RemoteObject:
+        async def call(context: int) -> RemoteObject:
+            async with _receiver(self.cdp, context, node) as object_id:
+                payload = script.arguments.model_validate({} if args is None else args)
+                result = await self.cdp.runtime.call_function_on(
+                    function_declaration=script.declaration,
+                    execution_context_id=context if object_id is None else None,
+                    object_id=object_id,
+                    arguments=[
+                        CallArgument(
+                            value=payload.model_dump(mode="json", by_alias=True)
+                        ),
+                        *(CallArgument(object_id=handle) for handle in objects),
+                    ],
+                    return_by_value=by_value,
+                    await_promise=True,
+                    user_gesture=user_gesture,
+                )
+                if result.exception_details:
+                    raise BrowserError(failure(script, result.exception_details))
+                return result.result
+
+        result = await self.worlds.run(
+            self.cdp, self.id, self.document_id, call, retry=not objects
+        )
+        return script.parse(result.value) if by_value else result
+
+
+@asynccontextmanager
+async def _receiver(
+    cdp: CdpSession, context: int, backend_node_id: int | None
+) -> AsyncGenerator[str | None, None]:
+    """Resolve `this` in the isolated world and release it on every exit path."""
+    if backend_node_id is None:
+        yield None
+        return
+    try:
+        resolved = await cdp.dom.resolve_node(
+            backend_node_id=backend_node_id, execution_context_id=context
+        )
+    except CDPCommandError as error:
+        raise BrowserError("STALE_ELEMENT") from error
+    object_id = resolved.object.object_id
+    if object_id is None:
+        raise BrowserError("STALE_ELEMENT")
+    try:
+        yield object_id
+    finally:
+        with suppress(CDPCommandError):
+            await cdp.runtime.release_object(object_id=object_id)

browserrig/browser/frames.py

@@ -0,0 +1,116 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import replace
+
+from cdpify import CdpSession
+from cdpify.domains.page import FrameTree
+from cdpify.domains.target import TargetInfo
+from cdpify.exceptions import CDPCommandError
+
+from browserrig.core import Bounds, BrowserError, FrameTransform
+from browserrig.scripts import OWNER_SIZE, VIEWPORT
+
+from .frame import Frame
+from .tab import Tab
+
+_MAX_FRAMES = 64
+_MAX_DEPTH = 8
+_FRAME_TIMEOUT = 2.0
+
+type _FrameSession = Callable[[str], Awaitable[CdpSession]]
+
+
+async def discover_frames(
+    tab: Tab, targets: tuple[TargetInfo, ...], session_for: _FrameSession
+) -> tuple[tuple[Frame, ...], tuple[str, ...]]:
+    """Return the tab's frames and why any were skipped.
+
+    Keep usable siblings when a frame detaches; bound work on frame-heavy pages.
+    """
+    root = await tab.frame_tree()
+    width, height = await (await tab.main_frame()).run(VIEWPORT)
+    viewport = Bounds(x=0, y=0, width=width, height=height)
+    result = [
+        Frame(
+            root.frame.id,
+            tab.cdp,
+            visible=viewport,
+            document_id=root.frame.loader_id,
+            worlds=tab.worlds,
+        )
+    ]
+    limitations: list[str] = []
+    target_map = {info.target_id: info for info in targets if info.type == "iframe"}
+    seen = {root.frame.id}
+
+    async def visit(
+        tree: FrameTree, parent: Frame, session_space: FrameTransform, depth: int
+    ):
+        children: dict[str, FrameTree | None] = {
+            child.frame.id: child for child in tree.child_frames or ()
+        }
+        # Some OOPIFs appear only in target discovery, not the embedding session's tree.
+        children.update(
+            (info.target_id, children.get(info.target_id))
+            for info in targets
+            if info.type == "iframe" and info.parent_frame_id == parent.id
+        )
+        for frame_id, child_tree in children.items():
+            if frame_id in seen:
+                continue
+            seen.add(frame_id)
+            if len(result) >= _MAX_FRAMES or depth >= _MAX_DEPTH:
+                limitations.append("Frame count or nesting limit reached")
+                return
+            try:
+                async with asyncio.timeout(_FRAME_TIMEOUT):
+                    child = await inspect(frame_id, parent, session_space)
+                    if child is None:
+                        continue
+                    if frame_id in target_map:
+                        child_tree = await child.frame_tree()
+                    if child_tree is not None:
+                        child = replace(child, document_id=child_tree.frame.loader_id)
+                result.append(child)
+                if child_tree is not None:
+                    child_space = (
+                        child.transform if frame_id in target_map else session_space
+                    )
+                    await visit(child_tree, child, child_space, depth + 1)
+            except (CDPCommandError, BrowserError, TimeoutError, ValueError):
+                limitations.append(
+                    f"Frame {frame_id} changed or could not be inspected"
+                )
+
+    async def inspect(
+        frame_id: str, parent: Frame, space: FrameTransform
+    ) -> Frame | None:
+        owner = await parent.cdp.dom.get_frame_owner(frame_id=frame_id)
+        child = Frame(
+            frame_id,
+            parent.cdp,
+            parent=parent,
+            owner_id=owner.backend_node_id,
+            worlds=tab.worlds,
+        )
+        size = await child.run_on_owner(OWNER_SIZE)
+        if not size or min(size) <= 0:
+            return None
+        box = await parent.cdp.dom.get_box_model(backend_node_id=owner.backend_node_id)
+        transform = space.child(box.model.content, *size)
+        visible = transform.bounds_to_viewport(
+            Bounds(x=0, y=0, width=size[0], height=size[1])
+        )
+        visible = visible.intersect(parent.visible or viewport)
+        # BoxModel quads are relative to the CDP session's root, not the parent frame.
+        cdp = await session_for(frame_id) if frame_id in target_map else parent.cdp
+        return replace(child, cdp=cdp, transform=transform, visible=visible)
+
+    try:
+        async with asyncio.timeout(10):
+            await visit(root, result[0], FrameTransform(), 0)
+    except TimeoutError:
+        limitations.append(
+            "Frame discovery timed out; some frames could not be inspected"
+        )
+    return tuple(result), tuple(dict.fromkeys(limitations))

browserrig/browser/images.py

@@ -0,0 +1,23 @@
+from cdpify.domains.page import Viewport
+
+from browserrig.core import Geometry
+
+from .tab import Tab
+
+
+async def screenshot(tab: Tab, geometry: Geometry | None = None) -> str:
+    clip = (
+        None
+        if geometry is None
+        else Viewport(
+            x=geometry.x,
+            y=geometry.y,
+            width=geometry.width,
+            height=geometry.height,
+            scale=geometry.scale,
+        )
+    )
+    result = await tab.cdp.page.capture_screenshot(
+        format="png", clip=clip, capture_beyond_viewport=False
+    )
+    return result.data

browserrig/browser/input.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Coroutine
+from typing import TYPE_CHECKING, Any, Literal
+
+from cdpify.domains.input import MouseButton
+
+from browserrig.core import CursorStyle, MouseEventKind, Point
+from browserrig.events import InputEvent
+from browserrig.input import KeyEventType
+from browserrig.scripts import CURSOR, CursorArgs
+
+if TYPE_CHECKING:
+    from .tab import Tab
+
+# A cursor shape is presentation only and must never hold up input.
+_CURSOR_PROBE_SECONDS = 0.25
+
+
+class CdpInput:
+    """Native input transport for the browser's devices, bound to one tab session.
+
+    This adapter owns CDP dispatch and dialog handling; Mouse and Keyboard own
+    gestures, device state and pacing.
+    """
+
+    def __init__(self, tab: Tab) -> None:
+        self._tab = tab
+        self.dialog_opened = asyncio.Event()
+
+    @property
+    def id(self) -> str:
+        return self._tab.id
+
+    async def viewport_size(self) -> tuple[float, float]:
+        return await self._tab.viewport_size()
+
+    def layout_changed(self) -> None:
+        self._tab.layout_changed()
+
+    async def emit(self, event: InputEvent) -> None:
+        await self._tab.emit(event)
+
+    async def cursor_style(self, point: Point) -> CursorStyle | None:
+        """Return the CSS cursor under a viewport point, or None when the page cannot say."""
+        if self._tab.dialog is not None:
+            return None
+        try:
+            async with asyncio.timeout(_CURSOR_PROBE_SECONDS):
+                frame = await self._tab.main_frame()
+                style = await frame.run(CURSOR, CursorArgs(x=point.x, y=point.y))
+        except Exception:  # pylint: disable=broad-exception-caught
+            # Navigation, dialogs and detached sessions must not fail the input itself.
+            return None
+        return CursorStyle.parse(style)
+
+    async def dispatch_mouse(
+        self,
+        kind: Literal[
+            MouseEventKind.MOVED, MouseEventKind.PRESSED, MouseEventKind.RELEASED
+        ],
+        point: Point,
+        *,
+        button: MouseButton,
+        buttons: int,
+        click_count: int,
+    ) -> None:
+        await self._input(
+            self._tab.cdp.input.dispatch_mouse_event(
+                type=kind.value,
+                x=point.x,
+                y=point.y,
+                button=button,
+                buttons=buttons,
+                click_count=click_count,
+            )
+        )
+
+    async def dispatch_wheel(
+        self, point: Point, *, delta_x: float, delta_y: float
+    ) -> None:
+        await self._input(
+            self._tab.cdp.input.dispatch_mouse_event(
+                type=MouseEventKind.WHEEL.value,  # smelt: ignore[SMT318] -- cdpify wants a Literal
+                x=point.x,
+                y=point.y,
+                delta_x=delta_x,
+                delta_y=delta_y,
+            )
+        )
+
+    async def dispatch_key(
+        self,
+        kind: KeyEventType,
+        *,
+        modifiers: int,
+        key: str,
+        code: str,
+        windows_virtual_key_code: int,
+        text: str | None = None,
+    ) -> None:
+        await self._input(
+            self._tab.cdp.input.dispatch_key_event(
+                type=kind,
+                modifiers=modifiers,
+                key=key,
+                code=code,
+                windows_virtual_key_code=windows_virtual_key_code,
+                text=text,
+            )
+        )
+
+    async def cancel_drag(self) -> None:
+        await self._tab.cdp.input.cancel_dragging()
+
+    async def _input(self, command: Coroutine[Any, Any, None]) -> None:
+        """Send input, returning early when it opens a JavaScript dialog.
+
+        Chrome answers an input event only after its handlers finish, and an alert, confirm
+        or prompt holds them until the dialog closes. The input has landed by then, so the
+        reply is left to arrive later.
+        """
+        if self._tab.dialog is not None:
+            await command
+            return
+        # Started eagerly, input that needs no reply lands within the caller's step.
+        sent = asyncio.Task(command, loop=asyncio.get_running_loop(), eager_start=True)
+        if not sent.done():
+            opened = asyncio.ensure_future(self.dialog_opened.wait())
+            try:
+                await asyncio.wait((sent, opened), return_when=asyncio.FIRST_COMPLETED)
+            except asyncio.CancelledError:
+                sent.cancel()
+                raise
+            finally:
+                opened.cancel()
+        if not sent.done():
+            sent.add_done_callback(_discard_result)
+            return
+        sent.result()
+
+
+def _discard_result(task: asyncio.Future[None]) -> None:
+    # The reply of input that opened a dialog only reports when the dialog closed.
+    if not task.cancelled():
+        task.exception()

browserrig/browser/models.py

@@ -0,0 +1,8 @@
+from browserrig.core import Options
+
+
+class TabInfo(Options):
+    id: str
+    url: str
+    title: str
+    active: bool = False

browserrig/browser/plugin.py

@@ -0,0 +1,44 @@
+from dataclasses import dataclass
+
+from harnessed import Context, Inject, Plugin, SessionLog
+from harnessed.kernel import Event
+
+from browserrig.events import BROWSER_EVENTS
+
+from .base import Browser, BrowserEvents
+from .chrome import ChromeBrowser
+from .config import BrowserOptions, Launch
+from .tab import Tab
+
+
+class Chrome(Plugin, slot="browserrig.browser", needs=(SessionLog,)):
+    events = BROWSER_EVENTS
+
+    def __init__(self, options: BrowserOptions | None = None) -> None:
+        super().__init__()
+        self.options = options if options is not None else Launch()
+
+    async def setup(self, ctx: Context, log: Inject[SessionLog]) -> None:
+        async def tab_changed(tab: Tab, settled: bool) -> None:
+            await ctx.dispatch(TabChanged(tab, settled))
+
+        browser = await ctx.enter(
+            ChromeBrowser(
+                self.options,
+                emit=log.emit,
+                on_tab_change=tab_changed,
+            )
+        )
+        ctx.provide(Browser, browser)
+        ctx.provide(BrowserEvents, browser.events)
+
+
+@dataclass(frozen=True)
+class TabChanged(Event[None]):
+    """`tab` may show a new url, title or loading state, or has closed.
+
+    `settled` marks a page that stopped loading, so its document can be read.
+    """
+
+    tab: Tab
+    settled: bool