x

src/guide/app/browser/client.py

@@ -1,11 +1,18 @@
 import contextlib
 from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import TYPE_CHECKING
 
 from playwright.async_api import Page
 
 from guide.app.browser.extension_client import ExtensionPage
 from guide.app.browser.pool import BrowserPool
 
+if TYPE_CHECKING:
+    from playwright.async_api import StorageState
+else:
+    StorageState = dict[str, object]  # Runtime fallback
+
 
 class BrowserClient:
     """Provides page access via a persistent browser pool with context isolation.
@@ -30,7 +37,9 @@ class BrowserClient:
 
     @contextlib.asynccontextmanager
     async def open_page(
-        self, host_id: str | None = None
+        self,
+        host_id: str | None = None,
+        storage_state: StorageState | str | Path | None = None,
     ) -> AsyncIterator[Page | ExtensionPage]:
         """Get a fresh page from the pool with guaranteed isolation.
 
@@ -39,6 +48,8 @@ class BrowserClient:
 
         Args:
             host_id: The host identifier, or None for the default host
+            storage_state: Optional Playwright storage_state to initialize context.
+                           Only applies to headless mode.
 
         Yields:
             A Playwright Page instance
@@ -51,7 +62,9 @@ class BrowserClient:
         _logger = logging.getLogger(__name__)
         _logger.info(f"[BrowserClient] open_page called for host_id: {host_id}")
 
-        context, page, should_close = await self.pool.allocate_context_and_page(host_id)
+        context, page, should_close = await self.pool.allocate_context_and_page(
+            host_id, storage_state=storage_state
+        )
 
         _logger.info(f"[BrowserClient] Got page from pool, should_close: {should_close}")
         try: