pi-lean-dimension 0.2.4 → 0.3.0

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

@@ -1,8 +1,9 @@
 """
-Playwright Bridge Base — shared Playwright logic for Python browser bridges.
+PlaywrightBridge — Python browser automation bridge for Playwright-based backends.
 
-Extracts the Playwright-specific implementation from chromium-py/bridge.py
-into a parameterized base class.  Subclasses override:
+Provides JSON-RPC command routing, session lifecycle, element caching,
+and a ``run()`` main loop.  ``PlaywrightBridge`` is a concrete base
+class that subclasses override with engine-specific settings:
 
 * ``_plugin_name`` — e.g. ``"chromium-py"``, ``"firefox-py"``
 * ``_user_agent`` — fallback UA string (when dynamic probe is disabled or fails)
@@ -12,6 +13,28 @@ into a parameterized base class.  Subclasses override:
 
 All navigation, interaction, console, cookie, and storage operations
 are shared across engines.
+
+Protocol
+--------
+All communication is JSON-RPC 2.0 over stdin/stdout with newline-delimited
+framing.  See ``transport.py`` for details.
+
+Lifecycle
+---------
+1. The TypeScript ``PythonPluginAdapter`` spawns the Python process.
+2. The bridge starts its ``run()`` loop, waiting for commands.
+3. First command is typically ``browser.navigate``, which calls
+   ``create_browser_session()`` (if no session exists yet for that taskId)
+   and then navigates.
+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.
+
+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 base64
@@ -20,18 +43,32 @@ import os
 import re
 import sys
 import time
+import traceback
 from typing import Any, Optional
 from urllib.parse import unquote as _urlunquote
 
-from .bridge import BrowserBridge, SessionNotFoundError
 from .bot_detection import check_bot_detection
-from .accessibility import parse_snapshot, build_locator_args
+from .accessibility import parse_snapshot, build_locator_args, AriaParseResult
 from .browser_data import NAV_SETTLE
+from .transport import (
+    read_request,
+    write_response,
+    make_success_response,
+    make_error_response,
+    make_parse_error,
+    make_invalid_request,
+    make_application_error,
+    InvalidRequestError,
+    METHOD_NOT_FOUND,
+    INVALID_PARAMS,
+    SESSION_ERROR,
+)
 
 # ─── Playwright import (lazy, for better error messages) ──────────────
 
 try:
     from playwright.sync_api import sync_playwright, TimeoutError as PlaywrightTimeout  # type: ignore[import-unresolved]
+
     HAS_PLAYWRIGHT = True
 except ImportError:
     HAS_PLAYWRIGHT = False
@@ -39,11 +76,28 @@ except ImportError:
     PlaywrightTimeout = TimeoutError  # type: ignore[misc]
 
 
+# ─── Default timeout ──────────────────────────────────────────────────
+
+DEFAULT_NAVIGATION_TIMEOUT_MS: int = 30_000
+DEFAULT_INTERACTION_TIMEOUT_MS: int = 10_000
+
+
 # ─── Nav-settle constants (loaded from shared browser-data.json) ──────
 
 _DOM_STABILIZE_JS: str = NAV_SETTLE["domStabilizationJs"]
 
 
+# ─── Custom exceptions ────────────────────────────────────────────────
+
+
+class SessionNotFoundError(Exception):
+    """Raised when an operation requires a session but none exists."""
+
+
+class InvalidParamsError(Exception):
+    """Raised when a required parameter is missing or has the wrong type."""
+
+
 # ─── Shared helper for bridge entry points ───────────────────────────
 
 
@@ -64,16 +118,20 @@ def check_playwright_or_exit(browser: str) -> None:
             "  pip install playwright\n"
             f"  playwright install {browser}\n"
         )
-        print(json.dumps({
-            "jsonrpc": "2.0",
-            "id": None,
-            "error": {"code": -32000, "message": msg.strip()},
-        }))
+        print(
+            json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "id": None,
+                    "error": {"code": -32000, "message": msg.strip()},
+                }
+            )
+        )
         sys.stdout.flush()
         sys.exit(1)
 
 
-class PlaywrightBridge(BrowserBridge):
+class PlaywrightBridge:
     """Base class for Playwright-based browser bridges.
 
     Subclasses must set these class/instance attributes:
@@ -109,14 +167,14 @@ class PlaywrightBridge(BrowserBridge):
     #: Engine-specific install hint (shown when browser executable missing).
     _install_hint: str = ""
 
-    # ── Stealth quirks (Phase 0) ──────────────────────────────────
+    # ── Stealth quirks ───────────────────────────────────────────────
     #
     # These opt-in flags let stealth subclasses (Camoufox and other stealth engines)
     # disable the base's hard-coded Playwright defaults that would otherwise
     # clobber a fingerprint-managed browser context.  All default to ``off``
     # so the shipped ``chromium-py`` / ``firefox-py`` bridges are bit-identical.
     #
-    # See stealth-browser-plan-v3.md "Quirks schema" for the concrete
+    # See the portal AGENTS.md quirks table for the concrete
     # correctness problem each flag fixes.
 
     #: When True, ``create_browser_context()`` does NOT pass ``viewport`` or
@@ -134,9 +192,14 @@ class PlaywrightBridge(BrowserBridge):
     _eval_prefix: str = ""
 
     #: When True, ``do_scroll`` uses ``page.mouse.wheel`` instead of
-    #: ``page.evaluate("window.scrollBy")``.  The eval-based scroll is a
-    #: write that silently no-ops under Camoufox's isolated world; the wheel
-    #: event performs the scroll via input events instead.
+    #: ``page.evaluate("window.scrollBy")``.  On older Camoufox binaries
+    #: (``135.0.1-beta.24`` and earlier) the eval-based scroll was a write
+    #: that silently no-op'd under the isolated world, so the wheel event
+    #: was the only path that moved the page.  On ``152.0.4-beta.27+`` the
+    #: wheel event itself no-ops (the ``wheel`` listener never fires) while
+    #: the eval-based ``window.scrollBy`` now works — so the flag must be
+    #: ``False`` on the current binary.  Default ``False`` (eval scroll);
+    #: only set ``True`` for the legacy Camoufox binary.
     _scroll_via_wheel: bool = False
 
     #: When True, ``create_browser_context`` passes ``no_viewport=True`` to
@@ -235,6 +298,43 @@ class PlaywrightBridge(BrowserBridge):
     #: Default ``False`` so shipped bridges stay bit-identical.
     _csp_safe_readonly_via_init_script: bool = False
 
+    #: When non-zero, ``_wait_for_navigation_settle`` uses this as the
+    #: settle poll budget (ms) instead of the default 400.  Stealth backends
+    #: whose patched browser fires navigation events with higher latency
+    #: (e.g. Camoufox's Juggler) set a larger value to avoid settling before
+    #: the navigation commit is observable.  Default 400 matches the
+    #: historical hard-coded value so shipped chromium-py / firefox-py are
+    #: unchanged.
+    _settle_budget_ms: int = 400
+
+    #: When True, ``_wait_for_navigation_settle`` switches the no-nav
+    #: polling branch from a fixed budget to "URL stable for 150 ms **or**
+    #: budget exhausted".  Stealth backends whose patched Juggler fires
+    #: ``page.url`` updates with higher latency set this along with a wider
+    #: :attr:`_settle_budget_ms` so the settle waits for the URL to
+    #: stabilize at the target value before declaring no navigation
+    #: occurred.  Default ``False`` so shipped chromium-py / firefox-py keep
+    #: the current tight settle behaviour.
+    _url_stability_settle: bool = False
+
+    # ── Session storage (persists across RPC calls) ─────────────
+
+    #: Per-taskId session data: {task_id: {...}}.
+    #: The dict contents are backend-specific (page, context, etc.).
+    sessions: dict[str, dict[str, Any]]
+
+    #: Per-taskId element cache: {task_id: AriaParseResult}.
+    element_caches: dict[str, AriaParseResult]
+
+    #: 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]
 
     # ── Shared Playwright state ─────────────────────────────────
 
@@ -242,7 +342,10 @@ class PlaywrightBridge(BrowserBridge):
     _browser: Any  # Browser instance (lazy, shared)
 
     def __init__(self) -> None:
-        super().__init__()
+        self.sessions = {}
+        self.element_caches = {}
+        self._running = False
+        self._plugin_config = {}
         self._pw = None
         self._browser = None
         self._cached_ua: str = ""
@@ -254,6 +357,52 @@ class PlaywrightBridge(BrowserBridge):
         # the extractor's stale result.
         self._readonly_extractor_script: str = ""
 
+    # ── 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
+
+    # ── Session helpers ─────────────────────────────────────────
+
+    def get_session(self, task_id: str) -> Optional[dict[str, Any]]:
+        """Get the session data for a task, or None."""
+        return self.sessions.get(task_id)
+
+    def require_session(self, task_id: str) -> dict[str, Any]:
+        """Get the session for a task, raising SESSION_ERROR if absent."""
+        session = self.get_session(task_id)
+        if session is None:
+            raise SessionNotFoundError(
+                f"No active session for task '{task_id}'. Call browser.navigate first."
+            )
+        return session
+
+    def ensure_session(
+        self, task_id: str, config: Optional[dict[str, Any]] = None
+    ) -> dict[str, Any]:
+        """Get or create a session for the given task."""
+        session = self.get_session(task_id)
+        if session is not None:
+            return session
+        new_session = self.create_browser_session(task_id, config or {})
+        self.sessions[task_id] = new_session
+        return new_session
+
+    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)
+
+    def set_element_cache(self, task_id: str, result: AriaParseResult) -> None:
+        """Store a parsed element cache for a task."""
+        self.element_caches[task_id] = result
+
     # ── Subclass extension point ───────────────────────────────
 
     def _launch_browser(self) -> Any:
@@ -304,7 +453,6 @@ class PlaywrightBridge(BrowserBridge):
                 except Exception:
                     pass
 
-
     # ── Debug logging ───────────────────────────────────────────
 
     @property
@@ -345,7 +493,11 @@ class PlaywrightBridge(BrowserBridge):
                 raise RuntimeError(
                     "Playwright is not installed. "
                     "Run: pip install playwright && "
-                    + (self._install_hint.lower() if self._install_hint else "playwright install <browser>")
+                    + (
+                        self._install_hint.lower()
+                        if self._install_hint
+                        else "playwright install <browser>"
+                    )
                 )
             self._pw = sync_playwright().start()  # type: ignore[union-attr]
             try:
@@ -431,8 +583,12 @@ class PlaywrightBridge(BrowserBridge):
                     snapshots=True,
                     sources=True,
                 )
-                self._log("tracing", taskId=config.get("_task_id", "shared"),
-                          action="start", dir=_trace_dir)
+                self._log(
+                    "tracing",
+                    taskId=config.get("_task_id", "shared"),
+                    action="start",
+                    dir=_trace_dir,
+                )
             except Exception:
                 pass  # Best-effort
 
@@ -542,14 +698,19 @@ class PlaywrightBridge(BrowserBridge):
 
         # ── Dialog auto-dismissal ───────────────────────────────
         dialog_log: list[dict[str, str]] = []
-        page.on("dialog", lambda dialog: (
-            dialog_log.append({
-                "type": dialog.type,
-                "message": dialog.message[:200],
-                "handledAs": "accepted",
-            }),
-            dialog.accept(),
-        ))
+        page.on(
+            "dialog",
+            lambda dialog: (
+                dialog_log.append(
+                    {
+                        "type": dialog.type,
+                        "message": dialog.message[:200],
+                        "handledAs": "accepted",
+                    }
+                ),
+                dialog.accept(),
+            ),
+        )
 
         return {
             "page": page,
@@ -605,8 +766,7 @@ class PlaywrightBridge(BrowserBridge):
                         f"trace-{task_id}-{int(time.time() * 1000)}.zip",
                     )
                     context.tracing.stop(path=_trace_path)
-                    self._log("tracing", taskId=task_id, action="stop",
-                              dir=_trace_dir)
+                    self._log("tracing", taskId=task_id, action="stop", dir=_trace_dir)
                 except Exception:
                     pass
 
@@ -667,18 +827,22 @@ class PlaywrightBridge(BrowserBridge):
         parsed = parse_snapshot(snap_text)
         self.set_element_cache(task_id, parsed)
 
-        return parsed.text, parsed.count, {
-            ref: {
-                "role": node.role,
-                "name": node.name,
-                "props": list(node.props),
-                "depth": node.depth,
-                "raw": node.raw,
-                "occurrenceIndex": node.occurrence_index,
-                "parentRef": node.parent_ref,
-            }
-            for ref, node in parsed.elements.items()
-        }
+        return (
+            parsed.text,
+            parsed.count,
+            {
+                ref: {
+                    "role": node.role,
+                    "name": node.name,
+                    "props": list(node.props),
+                    "depth": node.depth,
+                    "raw": node.raw,
+                    "occurrenceIndex": node.occurrence_index,
+                    "parentRef": node.parent_ref,
+                }
+                for ref, node in parsed.elements.items()
+            },
+        )
 
     def _build_interaction_result(
         self, task_id: str, page: Any, **extra: Any
@@ -705,9 +869,7 @@ class PlaywrightBridge(BrowserBridge):
             getattr(node, "name", "unknown") if node else "unknown",
         )
 
-    def _locate_element(
-        self, page: Any, task_id: str, ref: str
-    ) -> Any:
+    def _locate_element(self, page: Any, task_id: str, ref: str) -> Any:
         """Resolve an @e ref to a Playwright locator.
 
         Args:
@@ -746,7 +908,9 @@ class PlaywrightBridge(BrowserBridge):
     # ── Navigation settle helpers ───────────────────────────────
 
     @staticmethod
-    def _wait_for_page_ready(page: Any, timeout_ms: int, skip_networkidle: bool = False) -> None:
+    def _wait_for_page_ready(
+        page: Any, timeout_ms: int, skip_networkidle: bool = False
+    ) -> None:
         """Wait for page readiness after a navigation.
 
         Mirrors the TypeScript ``waitForPageReady`` helper — each load
@@ -772,19 +936,21 @@ class PlaywrightBridge(BrowserBridge):
             except Exception:
                 pass
 
-    @staticmethod
     def _wait_for_navigation_settle(
+        self,
         page: Any,
         url_before: str,
         nav_timeout_ms: int = 5000,
-        settle_timeout_ms: int = 400,
         skip_networkidle: bool = False,
     ) -> tuple[bool, str]:
         """Wait for navigation to settle after a user interaction.
 
-        Replaces fixed ``time.sleep()`` calls that race against navigation
-        commit.  Instead, listens for the ``framenavigated`` event and waits
-        for page readiness only when a navigation has actually started.
+        Listens for the ``framenavigated`` event and waits for page
+        readiness only when a navigation has actually started.
+
+        Uses :attr:`_settle_budget_ms` and :attr:`_url_stability_settle`
+        to allow stealth backends with higher event latency (e.g.
+        Camoufox's Juggler) to widen the settle window.
 
         Args:
             page: Playwright Page.
@@ -792,8 +958,7 @@ class PlaywrightBridge(BrowserBridge):
             nav_timeout_ms: Max time (ms) to wait for each page readiness
                             check (load and networkidle each get the full
                             budget). Default: 5000.
-            settle_timeout_ms: Short settle delay (ms) when no navigation
-                               occurs (default: 400).
+            skip_networkidle: When True, skip the ``networkidle`` wait.
 
         Returns:
             ``(navigated, url)`` — whether a main-frame navigation was
@@ -814,19 +979,53 @@ class PlaywrightBridge(BrowserBridge):
 
             waited_for_load = False
             if navigated:
-                PlaywrightBridge._wait_for_page_ready(page, nav_timeout_ms, skip_networkidle)
+                self._wait_for_page_ready(page, nav_timeout_ms, skip_networkidle)
                 waited_for_load = True
             elif page.url != url_before:
                 # URL changed without framenavigated event
-                PlaywrightBridge._wait_for_page_ready(page, nav_timeout_ms, skip_networkidle)
+                self._wait_for_page_ready(page, nav_timeout_ms, skip_networkidle)
                 waited_for_load = True
             else:
-                # No navigation — settle for client-side rerenders
-                page.wait_for_timeout(settle_timeout_ms)
+                # No navigation yet — poll for a late-starting navigation
+                # (e.g. ``setTimeout``-delayed redirects).  A fixed blind
+                # ``wait_for_timeout`` races the ``framenavigated`` event under
+                # load; polling at 50 ms granularity catches the nav as soon
+                # as it fires within the settle budget.
+                # ponytail: 50 ms poll, budget = self._settle_budget_ms
+                # (default 400, Camoufox 2000).  Switch to
+                # ``page.wait_for_function`` if sub-50 ms latency matters.
+                settle_budget = self._settle_budget_ms
+                remaining = settle_budget
+
+                if self._url_stability_settle:
+                    # URL-stability mode: wait for the URL to stabilize at a
+                    # new value for 150 ms, or until the budget expires.
+                    # Stealth backends with high Juggler event latency (e.g.
+                    # Camoufox) benefit from confirming the URL has finished
+                    # changing before declaring no navigation occurred.
+                    url_stable_since: float | None = None
+                    while remaining > 0 and not navigated:
+                        page.wait_for_timeout(50)
+                        remaining -= 50
+                        if navigated:
+                            break
+                        if page.url != url_before:
+                            if url_stable_since is None:
+                                url_stable_since = time.monotonic()
+                            elif (time.monotonic() - url_stable_since) >= 0.150:
+                                break  # URL stable for 150 ms
+                        else:
+                            url_stable_since = None
+                else:
+                    # Original tight-poll mode: exit as soon as the URL
+                    # changes or the event fires.
+                    while remaining > 0 and not navigated and page.url == url_before:
+                        page.wait_for_timeout(50)
+                        remaining -= 50
 
             # Late-arrival gate: catch navigations that started during settle
             if not waited_for_load and (navigated or page.url != url_before):
-                PlaywrightBridge._wait_for_page_ready(page, nav_timeout_ms, skip_networkidle)
+                self._wait_for_page_ready(page, nav_timeout_ms, skip_networkidle)
 
         finally:
             page.remove_listener("framenavigated", _on_nav)
@@ -940,10 +1139,15 @@ class PlaywrightBridge(BrowserBridge):
             title = ""
 
         if last_error is None:
-            self._log("navigate", url=url, plugin=self._plugin_name,
-                      success=True, botDetected=bot_detected,
-                      elementCount=element_count,
-                      time=round((time.time() - _t_start) * 1000))
+            self._log(
+                "navigate",
+                url=url,
+                plugin=self._plugin_name,
+                success=True,
+                botDetected=bot_detected,
+                elementCount=element_count,
+                time=round((time.time() - _t_start) * 1000),
+            )
             return {
                 "success": True,
                 "url": page.url,
@@ -955,10 +1159,16 @@ class PlaywrightBridge(BrowserBridge):
                 "dialogEvents": self._get_dialog_events(task_id),
             }
         else:
-            self._log("navigate", url=url, plugin=self._plugin_name,
-                      success=False, botDetected=bot_detected,
-                      elementCount=element_count, error=last_error,
-                      time=round((time.time() - _t_start) * 1000))
+            self._log(
+                "navigate",
+                url=url,
+                plugin=self._plugin_name,
+                success=False,
+                botDetected=bot_detected,
+                elementCount=element_count,
+                error=last_error,
+                time=round((time.time() - _t_start) * 1000),
+            )
             return {
                 "success": False,
                 "url": url,
@@ -1011,8 +1221,9 @@ class PlaywrightBridge(BrowserBridge):
         try:
             locator = self._locate_element(page, task_id, ref)
         except RuntimeError as exc:
-            self._log("click", taskId=task_id, ref=ref, role=_role,
-                      name=_name, result="fail")
+            self._log(
+                "click", taskId=task_id, ref=ref, role=_role, name=_name, result="fail"
+            )
             return {"success": False, "error": str(exc)}
 
         try:
@@ -1020,21 +1231,30 @@ class PlaywrightBridge(BrowserBridge):
             locator.click(timeout=5_000)
 
             navigated, _ = self._wait_for_navigation_settle(
-                page, url_before, skip_networkidle=self._skip_networkidle,
+                page,
+                url_before,
+                skip_networkidle=self._skip_networkidle,
             )
 
             new_url = page.url
             new_title = page.title()
 
             result = self._build_interaction_result(
-                task_id, page, newUrl=new_url, newTitle=new_title,
+                task_id,
+                page,
+                newUrl=new_url,
+                newTitle=new_title,
             )
         except Exception as exc:
             result = {
                 "success": False,
                 "error": f"Click failed: {exc}",
             }
-        return self._log_op("click", {"taskId": task_id, "ref": ref, "role": _role, "name": _name}, result)
+        return self._log_op(
+            "click",
+            {"taskId": task_id, "ref": ref, "role": _role, "name": _name},
+            result,
+        )
 
     def do_type(self, task_id: str, ref: str, text: str) -> dict[str, Any]:
         _role, _name = self._ref_debug_info(task_id, ref)
@@ -1046,8 +1266,9 @@ class PlaywrightBridge(BrowserBridge):
         try:
             locator = self._locate_element(page, task_id, ref)
         except RuntimeError as exc:
-            self._log("type", taskId=task_id, ref=ref, role=_role,
-                      name=_name, result="fail")
+            self._log(
+                "type", taskId=task_id, ref=ref, role=_role, name=_name, result="fail"
+            )
             return {"success": False, "error": str(exc)}
 
         try:
@@ -1060,7 +1281,11 @@ class PlaywrightBridge(BrowserBridge):
                 "success": False,
                 "error": f"Type failed: {exc}",
             }
-        return self._log_op("type", {"taskId": task_id, "ref": ref, "role": _role, "name": _name}, result)
+        return self._log_op(
+            "type",
+            {"taskId": task_id, "ref": ref, "role": _role, "name": _name},
+            result,
+        )
 
     def do_scroll(self, task_id: str, direction: str) -> dict[str, Any]:
         page, err = self._get_page_or_error(task_id, "scroll")
@@ -1087,7 +1312,9 @@ class PlaywrightBridge(BrowserBridge):
                 "success": False,
                 "error": f"Scroll failed: {exc}",
             }
-        return self._log_op("scroll", {"taskId": task_id, "direction": direction}, result)
+        return self._log_op(
+            "scroll", {"taskId": task_id, "direction": direction}, result
+        )
 
     def do_go_back(self, task_id: str) -> dict[str, Any]:
         page, err = self._get_page_or_error(task_id, "goBack")
@@ -1136,7 +1363,9 @@ class PlaywrightBridge(BrowserBridge):
             page.keyboard.press(key)
 
             navigated, _ = self._wait_for_navigation_settle(
-                page, url_before, nav_timeout_ms=3000,
+                page,
+                url_before,
+                nav_timeout_ms=3000,
                 skip_networkidle=self._skip_networkidle,
             )
 
@@ -1144,7 +1373,10 @@ class PlaywrightBridge(BrowserBridge):
             new_title = page.title()
 
             result = self._build_interaction_result(
-                task_id, page, newUrl=new_url, newTitle=new_title,
+                task_id,
+                page,
+                newUrl=new_url,
+                newTitle=new_title,
             )
         except Exception as exc:
             result = {
@@ -1195,9 +1427,7 @@ class PlaywrightBridge(BrowserBridge):
                     "success": True,
                     "messages": [],
                 }
-            messages: list[dict[str, str]] = session.get(
-                "console_messages", []
-            )
+            messages: list[dict[str, str]] = session.get("console_messages", [])
             return {
                 "success": True,
                 "messages": messages,
@@ -1432,3 +1662,264 @@ class PlaywrightBridge(BrowserBridge):
                 "origins": [],
                 "error": str(exc),
             }
+
+    # ── 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.
+        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]:
+        """Route a JSON-RPC method to the appropriate operation handler.
+
+        Returns a JSON-RPC response dict (either result or error).
+        """
+        try:
+            handler = self._DISPATCH.get(method)
+            if handler is None:
+                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))
+        except NotImplementedError as exc:
+            return make_application_error(cmd_id, str(exc))
+        except Exception as exc:
+            tb = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+            return make_application_error(cmd_id, str(exc), traceback_str=tb)
+
+    # ── Main loop ─────────────────────────────────────────────
+
+    def run(self) -> None:
+        """Start the main JSON-RPC command loop.
+
+        Reads requests from stdin, dispatches them, and writes responses
+        to stdout.  Runs until EOF or a ``shutdown`` command.
+        """
+        self._running = True
+        while self._running:
+            try:
+                request = read_request()
+                if request is None:
+                    break  # EOF
+
+                cmd_id = request.get("id")
+                method = request.get("method", "")
+                params = request.get("params", {})
+
+                if not isinstance(params, dict):
+                    write_response(
+                        make_error_response(
+                            cmd_id,
+                            INVALID_PARAMS,
+                            '"params" must be a JSON object',
+                        )
+                    )
+                    continue
+
+                response = self.handle_command(method, params, cmd_id)
+                write_response(response)
+
+            except InvalidRequestError:
+                # Valid JSON but not a valid JSON-RPC Request object
+                write_response(make_invalid_request(None))
+            except ValueError:
+                # JSON parse error
+                write_response(make_parse_error(None))
+            except EOFError:
+                break
+            except KeyboardInterrupt:
+                break
+            except Exception as exc:
+                tb = "".join(
+                    traceback.format_exception(type(exc), exc, exc.__traceback__)
+                )
+                write_response(make_application_error(None, str(exc), traceback_str=tb))
+
+    # ── Internal helpers ──────────────────────────────────────
+
+    @staticmethod
+    def _require_param(
+        params: dict[str, Any],
+        key: str,
+        expected_type: type,
+    ) -> Any:
+        """Require a param to exist and be of the expected 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}"')
+        value = params[key]
+        if not isinstance(value, expected_type):
+            raise InvalidParamsError(
+                f'Parameter "{key}" must be of type {expected_type.__name__}, '
+                f"got {type(value).__name__}"
+            )
+        return value