refactor(typing): make mypy pydoll clean (136 → 0) without weakening the API

Unify the CDP/BiDi command model and tighten types end-to-end so the whole
package type-checks, while improving (not regressing) the public typing.

Core
- Unify Command into one generic TypedDict (protocol/base.py) with a phantom
  `response: NotRequired[R]` field, so the response type is structurally
  recoverable (mypy can't infer a TypedDict type arg that appears in no field);
  re-exported from cdp/base and bidi/base. execute_command and
  create_command_future are now generic (Command[P, R] -> R), dropping a
  `# type: ignore`.
- FindElementsMixin is generic over the element type: Tab.find()/query() return
  the concrete WebElement (CDP) / BiDiWebElement (BiDi) for full IDE
  autocomplete, while the shared protocols use Sequence[WebElementProtocol] so
  the concrete returns conform covariantly.

BiDi typing
- Discriminated unions via Literal `type` tags (input source actions,
  EvaluateResult); typed source-action construction for mouse/keyboard/scroll
  and element click.
- Real types for locateNodes params/result, ElementClipRectangle, and
  cookie/proxy/intercept/window/download construction (no more dict
  placeholders). Dynamic deserialization isolated to
  _deserialize_remote_value(Mapping) -> object.

WebElement conformance
- WebElement and BiDiWebElement now satisfy WebElementProtocol; implemented
  BiDiWebElement.get_children_elements / get_siblings_elements.

CDP↔generic convergence
- get_cookies/set_cookies convert between the portable Cookie types and CDP
  (chromium/_cookies.py); CDP-only cookie fields stay reachable via the escape
  hatch. set_window_bounds maps WindowBounds→Bounds; expect_download keeps the
  CDP DEFAULT reset via the escape hatch.

Misc: edge.py Options→ChromiumOptions; guard the browser-WS port; CDP event
tracker stores raw dicts (drops two `# type: ignore`s).

Tests: realistic CDP cookie fakes in the cookie round-trips; new BiDi relations
integration test. Unit 407 green; BiDi + CDP cookie integration green.

Author: thalissonvs

pydoll/browser/chromium/_cookies.py

@@ -0,0 +1,59 @@
+"""Conversion between protocol-agnostic cookies and CDP cookie types.
+
+The public surface (``Tab``/``Browser`` ``get_cookies``/``set_cookies``) speaks the
+portable ``pydoll.protocol.types`` cookie types. CDP commands use their own richer
+cookie types, so these helpers translate at the boundary. CDP-only fields (``session``,
+``priority``, ``partitionKey``, ...) are dropped on the way out; reach for them via the
+escape hatch ``execute_protocol_command(NetworkCommands.get_cookies())`` when needed.
+"""
+
+from __future__ import annotations
+
+from pydoll.protocol.cdp.network.types import Cookie as CDPCookie
+from pydoll.protocol.cdp.network.types import CookieParam as CDPCookieParam
+from pydoll.protocol.cdp.network.types import CookieSameSite
+from pydoll.protocol.types import Cookie, CookieParam
+
+
+def to_generic_cookies(cdp_cookies: list[CDPCookie]) -> list[Cookie]:
+    """Convert CDP cookies into protocol-agnostic cookies."""
+    return [_to_generic_cookie(cookie) for cookie in cdp_cookies]
+
+
+def _to_generic_cookie(cookie: CDPCookie) -> Cookie:
+    result = Cookie(
+        name=cookie['name'],
+        value=cookie['value'],
+        domain=cookie['domain'],
+        path=cookie['path'],
+        size=cookie['size'],
+        httpOnly=cookie['httpOnly'],
+        secure=cookie['secure'],
+        sameSite=cookie.get('sameSite', ''),
+    )
+    expires = cookie['expires']
+    if expires >= 0:
+        result['expiry'] = int(expires)
+    return result
+
+
+def to_cdp_cookie_params(cookies: list[CookieParam]) -> list[CDPCookieParam]:
+    """Convert protocol-agnostic cookie params into CDP cookie params."""
+    return [_to_cdp_cookie_param(cookie) for cookie in cookies]
+
+
+def _to_cdp_cookie_param(cookie: CookieParam) -> CDPCookieParam:
+    result = CDPCookieParam(name=cookie['name'], value=cookie['value'])
+    if 'domain' in cookie:
+        result['domain'] = cookie['domain']
+    if 'path' in cookie:
+        result['path'] = cookie['path']
+    if 'secure' in cookie:
+        result['secure'] = cookie['secure']
+    if 'httpOnly' in cookie:
+        result['httpOnly'] = cookie['httpOnly']
+    if 'expiry' in cookie:
+        result['expires'] = float(cookie['expiry'])
+    if 'sameSite' in cookie:
+        result['sameSite'] = CookieSameSite(cookie['sameSite'])
+    return result

pydoll/browser/chromium/base.py

@@ -14,6 +14,7 @@
 from typing import TYPE_CHECKING, Any, Awaitable, Callable, Optional, overload
 from urllib.parse import urlsplit, urlunsplit
 
+from pydoll.browser.chromium._cookies import to_cdp_cookie_params, to_generic_cookies
 from pydoll.browser.chromium.tab import Tab
 from pydoll.browser.intercepted_request import InterceptedRequest
 from pydoll.browser.managers import (
@@ -38,10 +39,10 @@
     InvalidWebSocketAddress,
     NoValidTabFound,
 )
+from pydoll.protocol.cdp.browser.types import Bounds, PermissionType
 from pydoll.protocol.cdp.browser.types import (
     DownloadBehavior as CDPDownloadBehavior,
 )
-from pydoll.protocol.cdp.browser.types import PermissionType
 from pydoll.protocol.cdp.fetch.events import FetchEvent
 from pydoll.protocol.cdp.fetch.types import AuthChallengeResponseType
 from pydoll.protocol.cdp.network.types import ErrorReason as CDPErrorReason
@@ -433,7 +434,9 @@ async def set_cookies(
     ):
         """Set multiple cookies in browser or context."""
         logger.debug(f'Setting {len(cookies)} cookies (context={browser_context_id})')
-        return await self._execute_command(StorageCommands.set_cookies(cookies, browser_context_id))
+        return await self._execute_command(
+            StorageCommands.set_cookies(to_cdp_cookie_params(cookies), browser_context_id)
+        )
 
     async def get_cookies(self, browser_context_id: Optional[str] = None) -> list[Cookie]:
         """Get all cookies from browser or context.
@@ -448,7 +451,7 @@ async def get_cookies(self, browser_context_id: Optional[str] = None) -> list[Co
         logger.debug(
             f'Retrieved {len(response["result"]["cookies"])} cookies (context={browser_context_id})'
         )
-        return response['result']['cookies']
+        return to_generic_cookies(response['result']['cookies'])
 
     async def get_version(self) -> BrowserVersion:
         """Get browser version information."""
@@ -501,7 +504,18 @@ async def set_window_bounds(self, bounds: WindowBounds):
         """
         window_id = await self._get_window_id()
         logger.info(f'Setting window bounds: id={window_id}, bounds={bounds}')
-        return await self._execute_command(BrowserCommands.set_window_bounds(window_id, bounds))
+        cdp_bounds: Bounds = {}
+        if 'width' in bounds:
+            cdp_bounds['width'] = bounds['width']
+        if 'height' in bounds:
+            cdp_bounds['height'] = bounds['height']
+        if 'x' in bounds:
+            cdp_bounds['left'] = bounds['x']
+        if 'y' in bounds:
+            cdp_bounds['top'] = bounds['y']
+        return await self._execute_command(
+            BrowserCommands.set_window_bounds(window_id, cdp_bounds)
+        )
 
     async def grant_permissions(
         self,

pydoll/browser/chromium/edge.py

@@ -10,7 +10,7 @@
 from pydoll.utils import validate_browser_paths
 
 if TYPE_CHECKING:
-    from pydoll.browser.chromium.options import Options
+    from pydoll.browser.chromium.options import ChromiumOptions
 
 logger = logging.getLogger(__name__)
 
@@ -20,7 +20,7 @@ class Edge(Browser):
 
     def __init__(
         self,
-        options: Optional[Options] = None,
+        options: Optional[ChromiumOptions] = None,
         connection_port: Optional[int] = None,
     ):
         """

pydoll/browser/chromium/tab.py

@@ -28,8 +28,10 @@
 
 import aiofiles
 
+from pydoll.browser.chromium._cookies import to_cdp_cookie_params, to_generic_cookies
 from pydoll.browser.requests import Request
 from pydoll.commands import (
+    BrowserCommands,
     DomCommands,
     FetchCommands,
     NetworkCommands,
@@ -61,7 +63,8 @@
 from pydoll.extractor.engine import ExtractionEngine
 from pydoll.interactions import KeyboardAPI, MouseAPI, ScrollAPI
 from pydoll.interactions.iframe import IFrameContext
-from pydoll.protocol.cdp.browser.types import DownloadBehavior, DownloadProgressState
+from pydoll.protocol.cdp.browser.types import DownloadBehavior as CDPDownloadBehavior
+from pydoll.protocol.cdp.browser.types import DownloadProgressState
 from pydoll.protocol.cdp.dom.types import Node, ShadowRootType
 from pydoll.protocol.cdp.network.types import ResourceType
 from pydoll.protocol.cdp.page.events import PageEvent
@@ -71,6 +74,7 @@
 )
 from pydoll.protocol.cdp.target.types import TargetInfo
 from pydoll.protocol.events import CDP_DOMAIN_MAP, CDP_EVENT_MAP, Event
+from pydoll.protocol.types import DownloadBehavior
 from pydoll.utils import (
     decode_base64_to_bytes,
     has_return_outside_function,
@@ -791,14 +795,14 @@ async def get_cookies(self) -> list[Cookie]:
             )
             cookies = response_storage['result']['cookies']
             logger.debug(f'Fetched {len(cookies)} cookies')
-            return cookies
+            return to_generic_cookies(cookies)
 
         response_network: NetworkGetCookiesResponse = await self._execute_command(
             NetworkCommands.get_cookies()
         )
         cookies = response_network['result']['cookies']
         logger.debug(f'Fetched {len(cookies)} cookies')
-        return cookies
+        return to_generic_cookies(cookies)
 
     async def get_network_response_body(self, request_id: str) -> str:
         """
@@ -858,7 +862,7 @@ async def set_cookies(self, cookies: list[CookieParam]):
         """
         logger.info(f'Setting {len(cookies)} cookies on current page')
         return await self._execute_command(
-            StorageCommands.set_cookies(cookies, self._browser_context_id)
+            StorageCommands.set_cookies(to_cdp_cookie_params(cookies), self._browser_context_id)
         )
 
     async def delete_all_cookies(self):
@@ -1115,8 +1119,7 @@ async def _fetch_document_html(self, frame_tree: FrameResourceTree) -> str:
             return html
         except Exception:
             logger.debug('getResourceContent failed for document, falling back to JS')
-            html = await self.execute_script('return document.documentElement.outerHTML')
-            return cast(str, html)
+            return str(await self.execute_script('return document.documentElement.outerHTML') or '')
 
     async def _fetch_bundle_assets(
         self,
@@ -1519,9 +1522,11 @@ async def _cleanup_download_context(
         download_dir: str,
     ) -> None:
         await self.remove_callback(cb_id_progress)
-        await self._browser.set_download_behavior(
-            behavior=DownloadBehavior.DEFAULT,
-            browser_context_id=self._browser_context_id,
+        await self._browser.execute_protocol_command(
+            BrowserCommands.set_download_behavior(
+                behavior=CDPDownloadBehavior.DEFAULT,
+                browser_context_id=self._browser_context_id,
+            )
         )
 
         if cleanup_dir: