pi-lean-dimension 0.1.0 → 0.2.0

package/node_modules/pi-lean-portal/backends/python-base/pi_browser_bridge/bridge.py

@@ -2,9 +2,9 @@
 BrowserBridge — base class for Python browser automation backends.
 
 Provides JSON-RPC command routing, session lifecycle, element caching,
-and a ``run()`` main loop.  Subclasses override ``create_browser_session()``
-and individual operation methods to implement specific browser backends
-(e.g. Chromium via Playwright, Camoufox, etc.).
+and a ``run()`` main loop.  Subclasses override ``create_browser_session()``,
+``create_browser_context()``, and the ``do_*`` operation methods to implement
+specific browser backends (e.g. Chromium via Playwright, Camoufox, etc.).
 
 Protocol
 --------
@@ -21,11 +21,28 @@ Lifecycle
 4. Subsequent commands use the existing session.
 5. ``browser.cleanup`` closes the session for a taskId.
 6. ``browser.shutdown`` (sent via cleanupAll) terminates the process.
+
+Subclass contract (all ``@abstractmethod``)
+--------------------------------------------
+* ``create_browser_session(task_id, config)`` — build a per-task session dict.
+* ``create_browser_context(config)`` — build an isolated BrowserContext.
+* ``do_navigate / do_snapshot / do_click / do_type / do_scroll / do_go_back
+  / do_press / do_screenshot / do_get_console_messages / do_clear_console
+  / do_evaluate / do_get_cookies / do_add_cookies / do_clear_cookies
+  / do_get_storage_state`` — the 15 operation methods.  Each returns a
+  dict whose shape is documented at the dispatch site (``_h_*`` handlers).
+  ``do_cleanup`` has a concrete default (calls ``close_browser_session``)
+  and need not be overridden.
+
+Named profiles are fully handled by the TypeScript side via
+``core/shared/storage-state.ts`` (disk persistence).  The Python
+bridge receives ``storageState`` in the navigate request and applies
+it when creating a new BrowserContext — it does NOT track shared
+contexts across tasks.
 """
 
-import inspect
-import sys
 import traceback
+from abc import ABC, abstractmethod
 from typing import Any, Optional
 
 from .transport import (
@@ -35,10 +52,8 @@ from .transport import (
     make_error_response,
     make_parse_error,
     make_invalid_request,
-    make_internal_error,
     make_application_error,
     InvalidRequestError,
-    APPLICATION_ERROR,
     METHOD_NOT_FOUND,
     INVALID_PARAMS,
     SESSION_ERROR,
@@ -51,23 +66,11 @@ DEFAULT_NAVIGATION_TIMEOUT_MS: int = 30_000
 DEFAULT_INTERACTION_TIMEOUT_MS: int = 10_000
 
 
-class BrowserBridge:
+class BrowserBridge(ABC):
     """Base class for Python browser automation bridges.
 
-    Subclass this and override:
-
-    * ``create_browser_session(task_id, config)`` — mandatory
-    * ``create_browser_context(config)`` — mandatory (creates isolated context per task)
-    * Any operation methods you want to customise (optional)
-    * ``close_browser_session(task_id)`` — optional (default unregisters)
-
-    Call ``run()`` to start the JSON-RPC command loop.
-
-        Named profiles are fully handled by the TypeScript side via
-    ``core/shared/storage-state.ts`` (disk persistence).  The Python
-    bridge receives ``storageState`` in the navigate request and applies
-    it when creating a new BrowserContext — it does NOT track shared
-    contexts across tasks.
+    Subclass this and override the abstract methods listed in the module
+    docstring.  Call ``run()`` to start the JSON-RPC command loop.
     """
 
     # ── Session storage ─────────────────────────────────────────
@@ -83,25 +86,40 @@ class BrowserBridge:
     #: Whether the bridge is still running.
     _running: bool
 
+    #: Plugin configuration dict forwarded from the TypeScript adapter via
+    #: the ``browser.init`` RPC.  Defaults to ``{}`` for bridges that never
+    #: receive an init call (e.g. older adapters, or the shipped
+    #: ``chromium-py``/``firefox-py`` when run standalone).  Subclasses read
+    #: engine-specific options from ``self.plugin_config.get("launch", {})``.
+    _plugin_config: dict[str, Any]
+
     def __init__(self) -> None:
         self.sessions = {}
         self.element_caches = {}
         self._running = False
+        self._plugin_config = {}
+
+    # ── Plugin config (forwarded via browser.init) ───────────────
+
+    @property
+    def plugin_config(self) -> dict[str, Any]:
+        """Return the plugin config dict forwarded from the TypeScript adapter.
+
+        Populated by the ``browser.init`` RPC handler.  Always returns a
+        dict (empty when no init was received) so subclasses can safely
+        call ``self.plugin_config.get("launch", {})``.
+        """
+        return self._plugin_config
 
     # ── Subclass hooks ──────────────────────────────────────────
 
+    @abstractmethod
     def create_browser_session(self, task_id: str, config: dict[str, Any]) -> dict[str, Any]:
         """Create a new browser session for the given task.
 
         Must return a dict that will be stored in ``self.sessions[task_id]``.
         The dict is backend-specific (e.g. containing a Playwright page/context).
-
-        Raises:
-            RuntimeError: if a session cannot be created.
         """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement create_browser_session()"
-        )
 
     def close_browser_session(self, task_id: str) -> None:
         """Close and clean up the session for the given task.
@@ -112,6 +130,7 @@ class BrowserBridge:
         self.sessions.pop(task_id, None)
         self.element_caches.pop(task_id, None)
 
+    @abstractmethod
     def create_browser_context(self, config: dict[str, Any]) -> Any:
         """Create a new isolated BrowserContext for a task session.
 
@@ -119,20 +138,7 @@ class BrowserBridge:
         tasks.  Named profiles are handled by the TypeScript side via
         ``core/shared/storage-state.ts`` — the ``config`` may contain
         ``storageState`` to restore cookies and localStorage.
-
-        Args:
-            config: Configuration dict (may contain ``storageState``,
-                    ``viewport``, ``userAgent``, etc.)
-
-        Returns:
-            A backend-specific BrowserContext object.
-
-        Raises:
-            NotImplementedError: if the subclass doesn't implement this.
         """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement create_browser_context()"
-        )
 
     # ── Session helpers ─────────────────────────────────────────
 
@@ -159,17 +165,6 @@ class BrowserBridge:
         self.sessions[task_id] = new_session
         return new_session
 
-    # ── Page session setup hook ──────────────────────────────────
-
-    def _setup_page_session(self, page: Any) -> dict[str, Any]:
-        """Set up event handlers (console capture, dialog dismissal) on a new page.
-
-        Base implementation returns a minimal session dict.  Subclasses
-        (e.g. ChromiumPyBridge) override this to attach console-message
-        accumulators and dialog handlers.
-        """
-        return {"page": page}
-
     def get_element_cache(self, task_id: str) -> Optional[AriaParseResult]:
         """Get the cached element parse result for a task, or None."""
         return self.element_caches.get(task_id)
@@ -179,7 +174,13 @@ class BrowserBridge:
         self.element_caches[task_id] = result
 
     # ── Operation stubs (override in subclasses) ────────────────
+    #
+    # The 15 ``do_*`` methods below are the operation contract.  Each
+    # returns a dict whose shape is enforced at the dispatch site
+    # (``_h_*`` handlers in ``_DISPATCH``).  ``do_cleanup`` has a concrete
+    # default and is not abstract.
 
+    @abstractmethod
     def do_navigate(
         self,
         task_id: str,
@@ -189,160 +190,63 @@ class BrowserBridge:
         profileName: Optional[str] = None,
         profileMode: Optional[str] = None,
     ) -> dict[str, Any]:
-        """Navigate the browser to a URL.
-
-        Subclasses interpret the extra params:
-
-        - ``storageState``: Playwright storage state for session restoration.
-        - ``profileName``: Named profile name (e.g. "work", "shopping").
-        - ``profileMode``: ``"none"`` / ``"session"`` / ``"named"``.
-          All modes create task-isolated BrowserContexts; named profiles
-          are handled by the TypeScript side via ``storageState``
-          (``core/shared/storage-state.ts``, disk persistence).
-
-        Must return a dict with keys:
-            success (bool), url (str), title (str),
-            snapshot (str), elementCount (int)
-        Optionally: botDetected (bool), profileName (str)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_navigate()"
-        )
+        """Navigate the browser to a URL."""
 
+    @abstractmethod
     def do_snapshot(self, task_id: str) -> dict[str, Any]:
-        """Take an accessibility snapshot of the current page.
-
-        Must return a dict with keys:
-            success (bool), snapshot (str), elementCount (int)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_snapshot()"
-        )
+        """Take an accessibility snapshot of the current page."""
 
+    @abstractmethod
     def do_click(self, task_id: str, ref: str) -> dict[str, Any]:
-        """Click an element by @e ref.
-
-        Must return a dict with keys:
-            success (bool)
-        Optionally: snapshot (str), elementCount (int), newUrl (str), newTitle (str)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_click()"
-        )
+        """Click an element by @e ref."""
 
+    @abstractmethod
     def do_type(self, task_id: str, ref: str, text: str) -> dict[str, Any]:
-        """Type text into an element by @e ref.
-
-        Must return a dict with keys:
-            success (bool)
-        Optionally: snapshot (str), elementCount (int), newUrl (str), newTitle (str)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_type()"
-        )
+        """Type text into an element by @e ref."""
 
+    @abstractmethod
     def do_scroll(self, task_id: str, direction: str) -> dict[str, Any]:
-        """Scroll the page up or down.
-
-        Must return a dict with keys:
-            success (bool)
-        Optionally: snapshot (str), elementCount (int), newUrl (str), newTitle (str)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_scroll()"
-        )
+        """Scroll the page up or down."""
 
+    @abstractmethod
     def do_go_back(self, task_id: str) -> dict[str, Any]:
-        """Navigate back in history.
-
-        Must return a dict with keys:
-            success (bool)
-        Optionally: snapshot (str), elementCount (int), newUrl (str), newTitle (str)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_go_back()"
-        )
+        """Navigate back in history."""
 
+    @abstractmethod
     def do_press(self, task_id: str, key: str) -> dict[str, Any]:
-        """Press a keyboard key on the current page (or focused element).
+        """Press a keyboard key on the current page (or focused element)."""
 
-        Must return a dict with keys:
-            success (bool)
-        Optionally: snapshot (str), elementCount (int), newUrl (str), newTitle (str)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_press()"
-        )
-
-    def do_screenshot(
-        self,
-        task_id: str,
-        full_page: bool = False,
-    ) -> dict[str, Any]:
-        """Take a screenshot of the current page.
-
-        Must return a dict with keys:
-            success (bool), dataUri (str) — JPEG base64 data URI
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_screenshot()"
-        )
+    @abstractmethod
+    def do_screenshot(self, task_id: str, full_page: bool = False) -> dict[str, Any]:
+        """Take a screenshot of the current page (JPEG base64 data URI)."""
 
+    @abstractmethod
     def do_get_console_messages(self, task_id: str) -> dict[str, Any]:
-        """Get captured console messages.
-
-        Must return a dict with keys:
-            success (bool), messages (list) — each with type, text
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_get_console_messages()"
-        )
+        """Get captured console messages."""
 
+    @abstractmethod
     def do_clear_console(self, task_id: str) -> dict[str, Any]:
-        """Clear captured console messages.
+        """Clear captured console messages."""
 
-        Must return a dict with keys:
-            success (bool)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_clear_console()"
-        )
-
-    def do_evaluate(self, task_id: str, expression: str) -> dict[str, Any]:
-        """Evaluate JavaScript in the page.
-
-        Must return a dict with keys:
-            success (bool)
-        Optionally: result (any)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_evaluate()"
-        )
+    @abstractmethod
+    def do_evaluate(
+        self, task_id: str, expression: str, *, read_only: bool = False
+    ) -> dict[str, Any]:
+        """Evaluate JavaScript in the page."""
 
+    @abstractmethod
     def do_get_cookies(
         self, task_id: str, urls: Optional[list[str]] = None
     ) -> dict[str, Any]:
-        """Get all cookies, optionally filtered by URL.
-
-        Must return a dict with keys:
-            success (bool), cookies (list) — each with name, value, domain, ...
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_get_cookies()"
-        )
+        """Get all cookies, optionally filtered by URL."""
 
+    @abstractmethod
     def do_add_cookies(
         self, task_id: str, cookies: list[dict[str, Any]]
     ) -> dict[str, Any]:
-        """Add cookies to the browser context.
-
-        Must return a dict with keys:
-            success (bool)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_add_cookies()"
-        )
+        """Add cookies to the browser context."""
 
+    @abstractmethod
     def do_clear_cookies(
         self,
         task_id: str,
@@ -350,38 +254,176 @@ class BrowserBridge:
         domain: Optional[str] = None,
         path: Optional[str] = None,
     ) -> dict[str, Any]:
-        """Clear cookies, optionally filtered by name/domain/path.
-
-        Must return a dict with keys:
-            success (bool)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_clear_cookies()"
-        )
+        """Clear cookies, optionally filtered by name/domain/path."""
 
+    @abstractmethod
     def do_get_storage_state(self, task_id: str) -> dict[str, Any]:
-        """Get full storage state (cookies + localStorage + IndexedDB).
-
-        Must return a dict with keys:
-            success (bool), cookies (list), origins (list)
-        """
-        raise NotImplementedError(
-            f"{type(self).__name__} must implement do_get_storage_state()"
-        )
+        """Get full storage state (cookies + localStorage + IndexedDB)."""
 
     def do_cleanup(self, task_id: str) -> dict[str, Any]:
         """Clean up resources for a specific task.
 
         Profile persistence is handled by the TypeScript side
         (``python-adapter.ts`` auto-saves storage state before calling
-        cleanup), so this method always calls ``close_browser_session()``.
-
-        Must return a dict with keys:
-            success (bool)
+        cleanup), so this default always calls ``close_browser_session()``.
         """
         self.close_browser_session(task_id)
         return {"success": True}
 
+    # ── Command handlers ────────────────────────────────────────
+    #
+    # One ``_h_*`` method per JSON-RPC method.  Each extracts params and
+    # calls the matching ``do_*`` method.  ``_DISPATCH`` (class attribute,
+    # built at the bottom of the class body) maps method name → handler.
+
+    def _h_ping(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        return make_success_response(cmd_id, "pong")
+
+    def _h_init(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        # Forward plugin config from the TypeScript adapter.  Sent exactly
+        # once after the ping handshake, before any other RPC.
+        self._plugin_config = params.get("config") or {}
+        return make_success_response(cmd_id, {"ok": True})
+
+    def _h_shutdown(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        self._running = False
+        return make_success_response(cmd_id, "shutting_down")
+
+    def _h_navigate(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        url = self._require_param(params, "url", str)
+        task_id = self._require_param(params, "taskId", str)
+        timeout_ms = params.get("timeoutMs", DEFAULT_NAVIGATION_TIMEOUT_MS)
+        result = self.do_navigate(
+            task_id, url, timeout_ms,
+            storageState=params.get("storageState"),
+            profileName=params.get("profileName"),
+            profileMode=params.get("profileMode"),
+        )
+        return make_success_response(cmd_id, result)
+
+    def _h_snapshot(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        return make_success_response(cmd_id, self.do_snapshot(task_id))
+
+    def _h_click(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        ref = self._require_param(params, "ref", str)
+        return make_success_response(cmd_id, self.do_click(task_id, ref))
+
+    def _h_type(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        ref = self._require_param(params, "ref", str)
+        text = self._require_param(params, "text", str)
+        return make_success_response(cmd_id, self.do_type(task_id, ref, text))
+
+    def _h_scroll(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        direction = self._require_param(params, "direction", str)
+        if direction not in ("up", "down"):
+            return make_error_response(
+                cmd_id, INVALID_PARAMS,
+                'direction must be "up" or "down"',
+            )
+        return make_success_response(cmd_id, self.do_scroll(task_id, direction))
+
+    def _h_go_back(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        return make_success_response(cmd_id, self.do_go_back(task_id))
+
+    def _h_press(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        key = self._require_param(params, "key", str)
+        return make_success_response(cmd_id, self.do_press(task_id, key))
+
+    def _h_screenshot(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        full_page = params.get("fullPage", False)
+        return make_success_response(cmd_id, self.do_screenshot(task_id, full_page))
+
+    def _h_get_console_messages(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        return make_success_response(cmd_id, self.do_get_console_messages(task_id))
+
+    def _h_clear_console(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        return make_success_response(cmd_id, self.do_clear_console(task_id))
+
+    def _h_evaluate(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        expression = self._require_param(params, "expression", str)
+        read_only = bool(params.get("readOnly", False))
+        result = self.do_evaluate(task_id, expression, read_only=read_only)
+        return make_success_response(cmd_id, result)
+
+    def _h_get_cookies(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        return make_success_response(cmd_id, self.do_get_cookies(task_id, params.get("urls")))
+
+    def _h_add_cookies(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        cookies = self._require_param(params, "cookies", list)
+        return make_success_response(cmd_id, self.do_add_cookies(task_id, cookies))
+
+    def _h_clear_cookies(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        # No required params beyond taskId — empty call clears ALL cookies
+        result = self.do_clear_cookies(
+            task_id, params.get("name"), params.get("domain"), params.get("path")
+        )
+        return make_success_response(cmd_id, result)
+
+    def _h_get_storage_state(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        return make_success_response(cmd_id, self.do_get_storage_state(task_id))
+
+    def _h_cleanup(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        task_id = self._require_param(params, "taskId", str)
+        return make_success_response(cmd_id, self.do_cleanup(task_id))
+
+    def _h_describe_quirks(self, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
+        # Return the bridge's declared quirks flags.  Uses getattr with
+        # defaults so a bare BrowserBridge (no Playwright quirks) returns
+        # all-defaults rather than raising AttributeError.
+        return make_success_response(cmd_id, {
+            "fingerprint_managed_context": getattr(
+                self, "_fingerprint_managed_context", False
+            ),
+            "eval_prefix": getattr(self, "_eval_prefix", ""),
+            "scroll_via_wheel": getattr(self, "_scroll_via_wheel", False),
+            "skip_default_viewport": getattr(self, "_skip_default_viewport", False),
+            "skip_networkidle": getattr(self, "_skip_networkidle", False),
+            "wrap_mw_eval_in_eval": getattr(self, "_wrap_mw_eval_in_eval", False),
+            "csp_safe_readonly_via_init_script": getattr(
+                self, "_csp_safe_readonly_via_init_script", False
+            ),
+        })
+
+    #: JSON-RPC method name → handler.  Built after the handlers are
+    #: defined so the names are in scope.  ``handle_command`` looks up
+    #: here and calls ``handler(self, params, cmd_id)``.
+    _DISPATCH = {
+        "ping": _h_ping,
+        "browser.init": _h_init,
+        "shutdown": _h_shutdown,
+        "browser.navigate": _h_navigate,
+        "browser.snapshot": _h_snapshot,
+        "browser.click": _h_click,
+        "browser.type": _h_type,
+        "browser.scroll": _h_scroll,
+        "browser.goBack": _h_go_back,
+        "browser.press": _h_press,
+        "browser.screenshot": _h_screenshot,
+        "browser.getConsoleMessages": _h_get_console_messages,
+        "browser.clearConsole": _h_clear_console,
+        "browser.evaluate": _h_evaluate,
+        "browser.getCookies": _h_get_cookies,
+        "browser.addCookies": _h_add_cookies,
+        "browser.clearCookies": _h_clear_cookies,
+        "browser.getStorageState": _h_get_storage_state,
+        "browser.cleanup": _h_cleanup,
+        "browser.describeQuirks": _h_describe_quirks,
+    }
+
     # ── Command routing ─────────────────────────────────────────
 
     def handle_command(self, method: str, params: dict[str, Any], cmd_id: Any) -> dict[str, Any]:
@@ -390,127 +432,12 @@ class BrowserBridge:
         Returns a JSON-RPC response dict (either result or error).
         """
         try:
-            if method == "ping":
-                return make_success_response(cmd_id, "pong")
-
-            if method == "shutdown":
-                self._running = False
-                return make_success_response(cmd_id, "shutting_down")
-
-            if method == "browser.navigate":
-                url = self._require_param(params, "url", str, cmd_id)
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                timeout_ms = params.get("timeoutMs", DEFAULT_NAVIGATION_TIMEOUT_MS)
-                storage_state = params.get("storageState")
-                profile_name = params.get("profileName")
-                profile_mode = params.get("profileMode")
-                result = self.do_navigate(
-                    task_id, url, timeout_ms,
-                    storageState=storage_state,
-                    profileName=profile_name,
-                    profileMode=profile_mode,
+            handler = self._DISPATCH.get(method)
+            if handler is None:
+                return make_error_response(
+                    cmd_id, METHOD_NOT_FOUND, f"Method not found: {method}"
                 )
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.snapshot":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                result = self.do_snapshot(task_id)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.click":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                ref = self._require_param(params, "ref", str, cmd_id)
-                result = self.do_click(task_id, ref)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.type":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                ref = self._require_param(params, "ref", str, cmd_id)
-                text = self._require_param(params, "text", str, cmd_id)
-                result = self.do_type(task_id, ref, text)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.scroll":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                direction = self._require_param(params, "direction", str, cmd_id)
-                if direction not in ("up", "down"):
-                    return make_error_response(
-                        cmd_id, INVALID_PARAMS,
-                        'direction must be "up" or "down"',
-                    )
-                result = self.do_scroll(task_id, direction)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.goBack":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                result = self.do_go_back(task_id)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.press":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                key = self._require_param(params, "key", str, cmd_id)
-                result = self.do_press(task_id, key)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.screenshot":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                full_page = params.get("fullPage", False)
-                result = self.do_screenshot(task_id, full_page)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.getConsoleMessages":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                result = self.do_get_console_messages(task_id)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.clearConsole":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                result = self.do_clear_console(task_id)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.evaluate":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                expression = self._require_param(params, "expression", str, cmd_id)
-                result = self.do_evaluate(task_id, expression)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.getCookies":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                urls = params.get("urls")
-                result = self.do_get_cookies(task_id, urls)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.addCookies":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                cookies = self._require_param(params, "cookies", list, cmd_id)
-                result = self.do_add_cookies(task_id, cookies)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.clearCookies":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                name = params.get("name")
-                domain = params.get("domain")
-                path = params.get("path")
-                # No required params beyond taskId — empty call clears ALL cookies
-                result = self.do_clear_cookies(task_id, name, domain, path)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.getStorageState":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                result = self.do_get_storage_state(task_id)
-                return make_success_response(cmd_id, result)
-
-            if method == "browser.cleanup":
-                task_id = self._require_param(params, "taskId", str, cmd_id)
-                result = self.do_cleanup(task_id)
-                return make_success_response(cmd_id, result)
-
-            # Unknown method
-            return make_error_response(
-                cmd_id,
-                METHOD_NOT_FOUND,
-                f"Method not found: {method}",
-            )
+            return handler(self, params, cmd_id)
 
         except SessionNotFoundError as exc:
             return make_error_response(cmd_id, SESSION_ERROR, str(exc))
@@ -570,12 +497,12 @@ class BrowserBridge:
         params: dict[str, Any],
         key: str,
         expected_type: type,
-        cmd_id: Any,
     ) -> Any:
         """Require a param to exist and be of the expected type.
 
-        Raises a JSON-RPC invalid params error if the param is missing
-        or has the wrong type.
+        Raises ``InvalidParamsError`` if the param is missing or has the
+        wrong type.  The caller's ``except Exception`` clause turns this
+        into a JSON-RPC application-error response.
         """
         if key not in params:
             raise InvalidParamsError(f'Missing required parameter: "{key}"')