funbrowser 0.1.0__py3-none-any.whl

funbrowser/element.py

@@ -0,0 +1,258 @@
+"""ElementHandle — a chainable reference to a DOM element in a Tab.
+
+Held by an opaque CDP ``objectId`` so the same JS object is targeted on each
+call even if the surrounding DOM mutates. Becomes stale (and methods will
+raise) after the page navigates away — get a fresh handle via ``tab.find`` or
+``tab.query`` after navigation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from . import humanly as _humanly
+
+if TYPE_CHECKING:
+    from .tab import Tab
+
+
+class ElementHandle:
+    __slots__ = ("_object_id", "_tab")
+
+    def __init__(self, tab: Tab, object_id: str) -> None:
+        self._tab = tab
+        self._object_id = object_id
+
+    @property
+    def object_id(self) -> str:
+        return self._object_id
+
+    async def _call(
+        self,
+        function_declaration: str,
+        args: list[Any] | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {
+            "objectId": self._object_id,
+            "functionDeclaration": function_declaration,
+            "returnByValue": True,
+            "awaitPromise": True,
+        }
+        if args is not None:
+            params["arguments"] = [{"value": a} for a in args]
+        result = await self._tab._cdp.send(
+            "Runtime.callFunctionOn", params, session_id=self._tab.session_id
+        )
+        if "exceptionDetails" in result:
+            raise RuntimeError(f"JS exception: {result['exceptionDetails'].get('text', '')}")
+        return result.get("result", {}).get("value")
+
+    async def _call_objects(
+        self,
+        function_declaration: str,
+        args: list[Any] | None = None,
+    ) -> list[str]:
+        """Call a function that returns an array of elements; return their objectIds."""
+        params: dict[str, Any] = {
+            "objectId": self._object_id,
+            "functionDeclaration": function_declaration,
+            "returnByValue": False,
+            "awaitPromise": True,
+        }
+        if args is not None:
+            params["arguments"] = [{"value": a} for a in args]
+        result = await self._tab._cdp.send(
+            "Runtime.callFunctionOn", params, session_id=self._tab.session_id
+        )
+        if "exceptionDetails" in result:
+            raise RuntimeError(f"JS exception: {result['exceptionDetails'].get('text', '')}")
+        array_id = result.get("result", {}).get("objectId")
+        if not array_id:
+            return []
+        props = await self._tab._cdp.send(
+            "Runtime.getProperties",
+            {"objectId": array_id, "ownProperties": True},
+            session_id=self._tab.session_id,
+        )
+        ids: list[str] = []
+        for prop in props.get("result", []):
+            if not prop.get("enumerable"):
+                continue
+            value = prop.get("value", {})
+            obj_id = value.get("objectId")
+            if obj_id and value.get("subtype") == "node":
+                ids.append(obj_id)
+        return ids
+
+    # ── interaction ────────────────────────────────────────────────────
+
+    async def click(self) -> None:
+        """Click via real Input.dispatchMouseEvent at the element's centre.
+
+        With ``humanly`` active on the tab the cursor curves toward the
+        target (cubic Bezier + ease-in-out), the button-press holds for a
+        random duration, and the impact point includes pixel-level jitter
+        — none of which are visible at the DOM level but all of which
+        modern antibots score on. Without humanly, it's an instant click.
+
+        Briefly retries (up to ~1.5s) on a zero-size box — covers elements
+        that are visible-soon (CSS transitions, ``display:none`` toggles,
+        late layout passes) without the caller having to wait explicitly.
+        """
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + 1.5
+        box = None
+        while True:
+            box = await self._call(
+                "function() {"
+                " this.scrollIntoView({block:'center', inline:'center'});"
+                " const r = this.getBoundingClientRect();"
+                " return {x:r.left+r.width/2, y:r.top+r.height/2,"
+                "         w:r.width, h:r.height};"
+                "}"
+            )
+            if box and box["w"] > 0 and box["h"] > 0:
+                break
+            if loop.time() >= deadline:
+                raise ValueError("element has zero size — cannot click")
+            await asyncio.sleep(0.05)
+        behaviour = self._tab._humanly
+        x, y = _humanly.jitter_target(behaviour, float(box["x"]), float(box["y"]))
+        await _humanly.move(self._tab, x, y)
+        await _humanly.pre_action_delay(behaviour)
+        await self._tab._send(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mousePressed",
+                "x": x,
+                "y": y,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+        await _humanly.click_hold(behaviour)
+        await self._tab._send(
+            "Input.dispatchMouseEvent",
+            {
+                "type": "mouseReleased",
+                "x": x,
+                "y": y,
+                "button": "left",
+                "clickCount": 1,
+            },
+        )
+        self._tab._cursor = (x, y)
+
+    async def focus(self) -> None:
+        await self._call("function() { this.focus(); }")
+
+    async def type(self, text: str, *, delay_ms: float = 0.0) -> None:
+        """Focus the element and insert ``text``.
+
+        ``delay_ms > 0`` pauses that long between characters. With ``humanly``
+        active and ``delay_ms == 0`` (the default), the pause is randomised
+        per keystroke using the tab's behaviour profile, so keystroke timing
+        looks like a real user instead of an even cadence.
+
+        Uses ``Input.insertText`` rather than synthesised ``keyDown``/``keyUp``
+        events — more reliable across IME / layout cases. If a caller needs
+        actual key codes (shortcuts, Tab key), reach for raw CDP directly.
+        """
+        await self.focus()
+        behaviour = self._tab._humanly
+        if delay_ms > 0:
+            for ch in text:
+                await self._tab._send("Input.insertText", {"text": ch})
+                await asyncio.sleep(delay_ms / 1000.0)
+        elif behaviour is not None:
+            for ch in text:
+                await self._tab._send("Input.insertText", {"text": ch})
+                await asyncio.sleep(_humanly.type_delay(behaviour))
+        else:
+            await self._tab._send("Input.insertText", {"text": text})
+
+    async def fill(self, value: str) -> None:
+        """Set ``element.value`` and dispatch input + change events.
+
+        Faster than typing for forms where the page only cares about the
+        final value. Use ``type`` when per-keystroke handlers matter.
+        """
+        await self._call(
+            "function(v) {"
+            " this.focus();"
+            " this.value = v;"
+            " this.dispatchEvent(new Event('input', {bubbles:true}));"
+            " this.dispatchEvent(new Event('change', {bubbles:true}));"
+            "}",
+            [value],
+        )
+
+    async def hover(self) -> None:
+        box = await self._call(
+            "function() {"
+            " this.scrollIntoView({block:'center', inline:'center'});"
+            " const r = this.getBoundingClientRect();"
+            " return {x:r.left+r.width/2, y:r.top+r.height/2};"
+            "}"
+        )
+        if not box:
+            raise ValueError("element not visible")
+        behaviour = self._tab._humanly
+        x, y = _humanly.jitter_target(behaviour, float(box["x"]), float(box["y"]))
+        await _humanly.move(self._tab, x, y)
+
+    # ── reading ────────────────────────────────────────────────────────
+
+    async def text(self) -> str:
+        return (await self._call("function(){return this.innerText;}")) or ""
+
+    async def value(self) -> str:
+        return (await self._call("function(){return this.value;}")) or ""
+
+    async def attribute(self, name: str) -> str | None:
+        result = await self._call("function(n){return this.getAttribute(n);}", [name])
+        return None if result is None else str(result)
+
+    async def html(self, *, outer: bool = True) -> str:
+        if outer:
+            return (await self._call("function(){return this.outerHTML;}")) or ""
+        return (await self._call("function(){return this.innerHTML;}")) or ""
+
+    async def is_visible(self) -> bool:
+        return bool(
+            await self._call(
+                "function(){"
+                " const r = this.getBoundingClientRect();"
+                " const s = window.getComputedStyle(this);"
+                " return r.width>0 && r.height>0 && s.display!=='none' && s.visibility!=='hidden';"
+                "}"
+            )
+        )
+
+    async def bounding_box(self) -> dict[str, float] | None:
+        result = await self._call(
+            "function(){"
+            " const r = this.getBoundingClientRect();"
+            " return {x:r.left, y:r.top, width:r.width, height:r.height};"
+            "}"
+        )
+        if result is None:
+            return None
+        return {k: float(v) for k, v in result.items()}
+
+    # ── nested queries ─────────────────────────────────────────────────
+
+    async def query(self, selector: str) -> ElementHandle | None:
+        ids = await self._call_objects(
+            "function(s){ const r=this.querySelector(s); return r ? [r] : []; }",
+            [selector],
+        )
+        return ElementHandle(self._tab, ids[0]) if ids else None
+
+    async def query_all(self, selector: str) -> list[ElementHandle]:
+        ids = await self._call_objects(
+            "function(s){ return Array.from(this.querySelectorAll(s)); }",
+            [selector],
+        )
+        return [ElementHandle(self._tab, i) for i in ids]

funbrowser/fingerprint/__init__.py

@@ -0,0 +1,14 @@
+"""Fingerprint customization — swap the JS-visible identity the browser presents.
+
+Use a preset (``presets.windows_11_nvidia_rtx_4070()``), build a custom
+``Fingerprint(...)``, or merge a preset with overrides via ``Fingerprint.merge``.
+
+Pass to ``funbrowser.start(fingerprint=...)`` — see ``examples/custom_fingerprint.py``.
+"""
+
+from __future__ import annotations
+
+from . import presets
+from .data import Fingerprint
+
+__all__ = ["Fingerprint", "presets"]

funbrowser/fingerprint/data.py

@@ -0,0 +1,74 @@
+"""The Fingerprint dataclass — every field optional; ``None`` means "don't override"."""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field, fields
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Fingerprint:
+    """A snapshot of overridable browser-identity values.
+
+    Every field is optional. ``None`` means "leave whatever Chrome reports
+    natively". Use :func:`merge` to layer overrides on top of a preset.
+    """
+
+    # ── User-Agent + Client Hints ────────────────────────────────────────
+    user_agent: str | None = None
+    accept_language: str | None = None
+    platform: str | None = None  # "Windows" / "macOS" / "Linux" / "Android"
+    platform_version: str | None = None  # "15.0.0" etc. for Sec-CH-UA-Platform-Version
+    architecture: str | None = None  # "x86" / "arm"
+    bitness: str | None = None  # "64" / "32"
+    mobile: bool | None = None
+    brands: tuple[tuple[str, str], ...] | None = None  # ((brand, version), ...)
+
+    # ── navigator.* ──────────────────────────────────────────────────────
+    languages: tuple[str, ...] | None = None
+    hardware_concurrency: int | None = None  # logical CPU cores
+    device_memory: float | None = None  # GB, Chrome reports {0.25,0.5,1,2,4,8}
+    max_touch_points: int | None = None
+
+    # ── screen / window ──────────────────────────────────────────────────
+    screen_width: int | None = None
+    screen_height: int | None = None
+    avail_width: int | None = None
+    avail_height: int | None = None
+    color_depth: int | None = None
+    device_pixel_ratio: float | None = None
+
+    # ── locale / time ────────────────────────────────────────────────────
+    timezone: str | None = None  # IANA, e.g. "America/New_York"
+    locale: str | None = None  # e.g. "en-US"
+
+    # ── WebGL ───────────────────────────────────────────────────────────
+    # Important: spoofing these without also faking the rendered pixel
+    # output (M9) can flag you with top-tier antibots. Default (None) keeps
+    # the real GPU value, which is usually what you want.
+    webgl_vendor: str | None = None
+    webgl_renderer: str | None = None
+
+    # ── meta ────────────────────────────────────────────────────────────
+    # Free-form label for debugging / logging. Never sent to the browser.
+    label: str = ""
+
+    # Tags useful for filtering presets programmatically.
+    tags: tuple[str, ...] = field(default_factory=tuple)
+
+    def merge(self, other: Fingerprint) -> Fingerprint:
+        """Return a new Fingerprint with ``other``'s non-None fields layered on."""
+        overrides: dict[str, Any] = {}
+        for f in fields(other):
+            value = getattr(other, f.name)
+            if f.name in ("label", "tags"):
+                if value:
+                    overrides[f.name] = value
+                continue
+            if value is not None:
+                overrides[f.name] = value
+        return dataclasses.replace(self, **overrides)
+
+    def has_webgl_override(self) -> bool:
+        return self.webgl_vendor is not None or self.webgl_renderer is not None