ysbrowser-sdk 0.11.0__py3-none-any.whl

ysbrowser_sdk/__init__.py

@@ -0,0 +1,20 @@
+"""Async context configuration for YSbrowser; Page and Locator remain native."""
+
+from .browser import YSBrowser, YSContext
+from .errors import SDKError, ConfigurationError, CompatibilityError, FingerprintLockedError, ProxyCheckError
+from .configuration import ContextConfig
+from .models import BrowserCapabilities, ProxyHealthResult, Direct, FingerprintProfile, ProxyCheck, ProxyConfig, ProxyStatus
+
+__version__ = "0.11.0"
+__all__ = [
+    "YSBrowser", "YSContext", "ContextConfig", "BrowserCapabilities", "ProxyHealthResult", "Direct", "FingerprintProfile", "ProxyCheck", "ProxyConfig",
+    "ProxyStatus", "SDKError", "ConfigurationError", "CompatibilityError",
+    "FingerprintLockedError", "ProxyCheckError", "__version__",
+]
+
+from .mouse import AsyncTrajectoryMouse as TrajectoryMouse, MotionExecution
+from .motion import TrajectoryModel, MotionPlan, MotionRequest
+__all__ += ["TrajectoryMouse", "TrajectoryModel", "MotionPlan", "MotionRequest", "MotionExecution"]
+
+from .options import ContextOptions
+__all__ += ["ContextOptions"]

ysbrowser_sdk/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

ysbrowser_sdk/_async_runtime.py

@@ -0,0 +1,34 @@
+"""Cancellation-aware ownership transfer for native resources."""
+import asyncio
+
+
+async def _settle(operation):
+    task = asyncio.ensure_future(operation)
+    cancelled = False
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            if task.cancelled():
+                raise
+            cancelled = True
+        except BaseException:
+            break
+    return task.result(), cancelled
+
+
+async def complete(operation):
+    """Finish cleanup despite repeated caller cancellation, then propagate it."""
+    result, cancelled = await _settle(operation)
+    if cancelled:
+        raise asyncio.CancelledError()
+    return result
+
+
+async def acquire(operation, cleanup):
+    """Never abandon a resource whose creation has reached the native driver."""
+    result, cancelled = await _settle(operation)
+    if cancelled:
+        await complete(cleanup(result))
+        raise asyncio.CancelledError()
+    return result

ysbrowser_sdk/_sync_runtime.py

@@ -0,0 +1,9 @@
+"""Sync equivalents: native calls complete before passing their result here."""
+
+
+def complete(result):
+    return result
+
+
+def acquire(result, cleanup):
+    return result

ysbrowser_sdk/async_api.py

@@ -0,0 +1,14 @@
+"""Native asynchronous Patchright API with YSbrowser configuration."""
+from .browser import YSBrowser, YSContext
+from .configuration import ContextConfig
+from .models import BrowserCapabilities, ProxyHealthResult, Direct, FingerprintProfile, ProxyCheck, ProxyConfig, ProxyStatus
+from .errors import SDKError, ConfigurationError, CompatibilityError, FingerprintLockedError, ProxyCheckError
+
+__all__ = ["YSBrowser", "YSContext", "ContextConfig", "BrowserCapabilities", "ProxyHealthResult", "Direct", "FingerprintProfile", "ProxyCheck", "ProxyConfig", "ProxyStatus", "SDKError", "ConfigurationError", "CompatibilityError", "FingerprintLockedError", "ProxyCheckError"]
+
+from .mouse import AsyncTrajectoryMouse as TrajectoryMouse, MotionExecution
+from .motion import TrajectoryModel, MotionPlan, MotionRequest
+__all__ += ["TrajectoryMouse", "TrajectoryModel", "MotionPlan", "MotionRequest", "MotionExecution"]
+
+from .options import ContextOptions
+__all__ += ["ContextOptions"]

ysbrowser_sdk/browser.py

@@ -0,0 +1,561 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import inspect
+import time
+from collections import deque
+import re
+import socket
+from pathlib import Path
+from typing import Any
+
+from patchright.async_api import Browser, BrowserContext, CDPSession, Page, async_playwright
+
+from .errors import CompatibilityError, ConfigurationError, FingerprintLockedError, ProxyCheckError, SDKError
+from .diagnostics import DiagnosticsMixin
+from .options import ContextOptions
+from .configuration import ContextConfig, write_json
+from .models import BrowserCapabilities, ProxyHealthResult, safe_url, Direct, FingerprintProfile, ProxyCheck, ProxyConfig, ProxyStatus
+from .mouse import AsyncTrajectoryMouse as TrajectoryMouse, MotionExecution
+from .motion import TrajectoryModel, MotionPlan, MotionRequest
+from ._async_runtime import acquire, complete
+from .runtime import launch_policy, runtime_info
+from .installer import get_browser_path
+
+
+class YSContext(DiagnosticsMixin):
+    """A configured context; raw is the original Patchright BrowserContext."""
+
+    @property
+    def options(self) -> ContextOptions:
+        """Return a detached copy of the options used to create this Context."""
+        return copy.deepcopy(self._options)
+
+    def __init__(self, owner: YSBrowser, raw: BrowserContext, context_id: str, name: str):
+        self._owner = owner
+        self.raw = raw
+        self.context_id = context_id
+        self.name = name
+        self._closed = False
+        self._gate = asyncio.Lock()
+        self._close_gate = asyncio.Lock()
+        self._fingerprint = FingerprintProfile()
+        self._proxy: ProxyConfig | Direct = Direct()
+        self._proxy_generation: str | None = None
+        self._no_viewport = True
+        self._options = ContextOptions()
+        self._recent_errors: deque[dict[str, Any]] = deque(maxlen=20)
+        self.raw.on("close", self._on_closed)
+        self.raw.on("requestfailed", self._on_request_failed)
+        self.raw.on("response", self._on_response)
+        self._init_diagnostics()
+
+    def _on_closed(self, *_: Any) -> None:
+        self._closed = True
+        self._diagnostic_trace = False
+        self._detach_diagnostics()
+        if self._owner._contexts.get(self.name) is self:
+            self._owner._contexts.pop(self.name, None)
+
+    def _on_request_failed(self, request: Any) -> None:
+        try:
+            if request.is_navigation_request():
+                match = re.search(r"net::ERR_[A-Z_]+", request.failure or "")
+                self._recent_errors.append({"kind": "navigation_network_error", "at": time.time() * 1000,
+                    "origin": safe_url(request.url), "network_error": match.group() if match else "unknown"})
+        except Exception:
+            pass
+
+    def _on_response(self, response: Any) -> None:
+        try:
+            if response.status >= 400 and response.request.is_navigation_request():
+                self._recent_errors.append({"kind": "navigation_http_error", "at": time.time() * 1000,
+                    "origin": safe_url(response.url), "http_status": response.status})
+        except Exception:
+            pass
+
+
+    def _ensure_open(self) -> None:
+        if self._owner._unexpected_disconnect:
+            raise SDKError("BROWSER_DISCONNECTED", "context", "Browser connection was lost; create a new browser and restore saved configuration/state", context_id=self.context_id)
+        if self._closed:
+            raise SDKError("CONTEXT_CLOSED", "context", "Context has been closed", context_id=self.context_id)
+
+    async def _send(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._ensure_open()
+        assert self._owner._cdp is not None
+        return await self._owner._cdp.send(method, {"browserContextId": self.context_id, **(params or {})})
+
+    async def fingerprint_status(self) -> dict[str, Any]:
+        try:
+            return (await self._send("Browser.getFingerprintProfile"))["status"]
+        except SDKError:
+            raise
+        except Exception as exc:
+            raise CompatibilityError("FINGERPRINT_STATUS_FAILED", "fingerprint.status",
+                                     "YSbrowser fingerprint CDP API is unavailable or failed", context_id=self.context_id,
+                                     original_error=exc) from None
+
+    async def _apply_fingerprint(self, profile: FingerprintProfile) -> None:
+        payload = profile.to_cdp()
+        capabilities = self._owner.capabilities
+        unknown = sorted(set(payload) - set(capabilities.fingerprint_fields))
+        if unknown:
+            raise CompatibilityError("UNSUPPORTED_FINGERPRINT_FIELDS", "fingerprint.set", "Browser does not support requested fingerprint fields", details={"fields": unknown})
+        if profile.server_gpu_profile is not None and (not capabilities.context_gpu_available or profile.server_gpu_profile not in capabilities.gpu_profiles):
+            raise ConfigurationError("Requested GPU profile is unsupported or Context GPU mode is unavailable")
+        status = await self.fingerprint_status()
+        if status["locked"]:
+            raise FingerprintLockedError("FINGERPRINT_LOCKED", "fingerprint.set",
+                                         "Create a new context; this context has already started a renderer", context_id=self.context_id)
+        try:
+            response = await self._send("Browser.setFingerprintProfile", {"profile": payload})
+            if profile.server_gpu_profile is not None and response.get("status", {}).get("profile", {}).get("serverGpuProfile") != profile.server_gpu_profile:
+                raise CompatibilityError("CONTEXT_GPU_UNSUPPORTED", "fingerprint.set",
+                                         "This browser does not acknowledge per-context GPU profiles; install the context GPU patch",
+                                         context_id=self.context_id)
+            self._fingerprint = profile
+        except CompatibilityError:
+            raise
+        except Exception as exc:
+            # Raw contexts may be manipulated by another client, so also inspect lock after failure.
+            status = await self.fingerprint_status()
+            if status["locked"]:
+                raise FingerprintLockedError("FINGERPRINT_LOCKED", "fingerprint.set", "A renderer started before configuration completed",
+                                             context_id=self.context_id, original_error=exc) from None
+            raise SDKError("FINGERPRINT_SET_FAILED", "fingerprint.set", "Browser rejected the profile; check supported values",
+                           context_id=self.context_id, original_error=exc) from None
+
+    async def set_fingerprint(self, profile: FingerprintProfile) -> None:
+        async with self._gate:
+            await self._apply_fingerprint(profile)
+
+    async def proxy_status(self) -> ProxyStatus:
+        try:
+            return ProxyStatus.from_cdp((await self._send("Browser.getProxyStatus"))["status"])
+        except SDKError:
+            raise
+        except Exception as exc:
+            raise CompatibilityError("PROXY_STATUS_FAILED", "proxy.status", "YSbrowser proxy CDP API is unavailable or failed",
+                                     context_id=self.context_id, original_error=exc) from None
+
+    async def _apply_proxy(self, proxy: ProxyConfig | Direct, check: ProxyCheck | None,
+                           mode: str | None = None, drain_timeout_ms: int | None = None) -> ProxyStatus:
+        if not isinstance(proxy, (ProxyConfig, Direct)) or (check is not None and not isinstance(check, ProxyCheck)):
+            raise ConfigurationError("proxy must be ProxyConfig or Direct; check must be ProxyCheck")
+        if self._options.client_certificates and not isinstance(proxy, Direct):
+            raise ConfigurationError('Client-certificate Contexts currently support Direct only; the native certificate tunnel bypasses runtime proxy changes')
+        if mode not in (None, "drain", "immediate"):
+            raise ConfigurationError("mode must be 'drain', 'immediate', or None (legacy)")
+        if drain_timeout_ms is not None and (type(drain_timeout_ms) is not int or not 1 <= drain_timeout_ms <= 60000):
+            raise ConfigurationError("drain_timeout_ms must be an integer between 1 and 60000")
+        if mode is None and drain_timeout_ms is not None:
+            raise ConfigurationError("drain_timeout_ms requires mode")
+        if mode is not None and not self._owner.capabilities.supports("proxySwitchBarrier"):
+            raise CompatibilityError("PROXY_SWITCH_UNSUPPORTED", "proxy.switch", "Install the browser proxy switch barrier patch", context_id=self.context_id)
+        payload = proxy.to_cdp()
+        if mode is not None:
+            payload["switchMode"] = mode
+            if drain_timeout_ms is not None:
+                payload["drainTimeoutMs"] = drain_timeout_ms
+        if check is not None:
+            payload.update(check.to_cdp())
+        try:
+            response = await self._send("Browser.setProxy", payload)
+        except Exception as exc:
+            try:
+                status = (await self.proxy_status()).to_dict()
+            except Exception:
+                status = {"check_state": "unavailable"}
+            # A failed command has no authoritative operation revision. Another
+            # CDP client may have changed the route before the follow-up query.
+            # Never associate unknown credentials with that observed revision.
+            switch_code = next((code for code in (
+                "PROXY_DRAIN_TIMEOUT", "PROXY_SWITCH_IN_PROGRESS",
+                "PROXY_SWITCH_CONTEXT_LOST", "PROXY_SWITCH_CANCELLED",
+                "PROXY_SWITCH_LEASE_EXPIRED", "PROXY_SWITCH_MULTIPLE_PARTITIONS_UNSUPPORTED",
+                "PROXY_SWITCH_BUSY_OR_INVALID") if code in str(exc)), None)
+            # A drain timeout or rejected concurrent operation does not apply a
+            # proxy. Preserve exportability only if the original revision remains.
+            unchanged = switch_code in ("PROXY_DRAIN_TIMEOUT", "PROXY_SWITCH_IN_PROGRESS", "PROXY_SWITCH_MULTIPLE_PARTITIONS_UNSUPPORTED") and status.get("generation") == self._proxy_generation
+            if not unchanged:
+                self._proxy_generation = None
+            if switch_code:
+                raise SDKError(switch_code, "proxy.switch", "Guarded proxy switch did not complete; inspect proxy_status before continuing", context_id=self.context_id,
+                               details={"proxy_status": status, "mode": mode}, original_error=exc) from None
+            error_class = ProxyCheckError if check is not None else SDKError
+            raise error_class("PROXY_CHECK_FAILED" if check is not None else "PROXY_SET_FAILED", "proxy.set",
+                              "Proxy operation failed; inspect status for rollback outcome", context_id=self.context_id,
+                              details={"proxy_status": status}, original_error=exc) from None
+        observed = ProxyStatus.from_cdp(response["status"])
+        self._proxy = proxy
+        self._proxy_generation = observed.generation
+        return observed
+
+    async def set_proxy(self, proxy: ProxyConfig | Direct, *, check: ProxyCheck | None = None,
+                        mode: str | None = None, drain_timeout_ms: int | None = None) -> ProxyStatus:
+        """Switch routes; explicit drain/immediate modes pause new native requests.
+
+        None preserves the legacy API. A drain timeout keeps the old proxy.
+        Long-lived streams count as active work; they can make drain time out.
+        Cancelling this Python await does not undo an already-issued CDP command.
+        """
+        async with self._gate:
+            return await self._apply_proxy(proxy, check, mode, drain_timeout_ms)
+
+    async def check_proxy(self, check_url: str, *, expected_exit_ip: str | None = None,
+                          timeout_ms: int = 10000) -> ProxyHealthResult:
+        check = ProxyCheck(check_url, expected_exit_ip=expected_exit_ip, timeout_ms=timeout_ms)
+        payload = check.to_cdp()
+        payload.pop("rollbackOnFailure")
+        # Intentionally no mutation lock: native generation/check IDs protect late results.
+        try:
+            result = ProxyHealthResult.from_cdp((await self._send("Browser.checkProxy", payload))["result"])
+        except SDKError:
+            raise
+        except Exception as exc:
+            raise SDKError("PROXY_CHECK_COMMAND_FAILED", "proxy.check", "Independent proxy check could not be completed by the protocol", context_id=self.context_id, original_error=exc) from None
+        return result
+
+    async def diagnostics(self) -> dict[str, Any]:
+        result: dict[str, Any] = {"context_id": self.context_id, "closed": self._closed,
+            "browser_connected": self._owner._browser is not None and self._owner._browser.is_connected(),
+            "versions": self._owner.diagnostics(), "recent_network_errors": copy.deepcopy(list(self._recent_errors))}
+        result['recent_page_events'] = [{k: v for k, v in e.items() if k != 'message'} for e in self._diagnostic_events]
+        result['diagnostics_collecting'] = self._diagnostic_enabled
+        if self._closed or self._owner._unexpected_disconnect:
+            return result
+        try:
+            fingerprint = await self.fingerprint_status()
+            result["fingerprint"] = {"locked": fingerprint["locked"],
+                "configured_fields": sorted(fingerprint["profile"]),
+                "server_gpu_profile": fingerprint["profile"].get("serverGpuProfile")}
+            result["proxy"] = (await self.proxy_status()).to_dict()
+        except SDKError as exc:
+            result["status_error"] = exc.to_dict()
+        return result
+
+    async def export_config(self, path: str | Path | None = None, *,
+                            include_proxy_credentials: bool = False, include_sensitive_options: bool = False) -> dict[str, Any]:
+        async with self._gate:
+            self._ensure_open()
+            proxy = await self.proxy_status()
+            fingerprint = await self.fingerprint_status()
+            if proxy.generation != self._proxy_generation or fingerprint["profile"] != self._fingerprint.to_cdp():
+                raise SDKError("CONFIG_CHANGED_EXTERNALLY", "context.export", "Current configuration cannot be confirmed from this SDK Context; reapply it successfully before exporting", context_id=self.context_id)
+            config = ContextConfig(self._fingerprint, self._proxy, self._no_viewport, self._options)
+            data = config.to_dict(include_proxy_credentials=include_proxy_credentials, include_sensitive_options=include_sensitive_options)
+            if path is not None:
+                write_json(path, data)
+            return data
+
+    async def save_storage_state(self, path: str | Path | None = None, *, indexed_db: bool = True) -> dict[str, Any]:
+        async with self._gate:
+            self._ensure_open()
+            if type(indexed_db) is not bool:
+                raise ConfigurationError("indexed_db must be boolean")
+            try:
+                state = await self.raw.storage_state(indexed_db=indexed_db)
+                if path is not None:
+                    write_json(path, state)
+                return state
+            except Exception as exc:
+                raise SDKError("STORAGE_SAVE_FAILED", "context.storage.save", "Could not export login storage state", context_id=self.context_id, original_error=exc) from None
+
+    async def restore_storage_state(self, state: dict[str, Any] | str | Path) -> None:
+        async with self._gate:
+            self._ensure_open()
+            if self.raw.pages:
+                raise SDKError("STORAGE_RESTORE_REQUIRES_EMPTY_CONTEXT", "context.storage.restore", "Restore before opening pages, preferably in a new Context", context_id=self.context_id)
+            try:
+                await self.raw.set_storage_state(state)
+            except Exception as exc:
+                raise SDKError("STORAGE_RESTORE_FAILED", "context.storage.restore", "Could not restore login storage state", context_id=self.context_id, original_error=exc) from None
+
+    def mouse(self, page: Page, *, model: TrajectoryModel | str | Path | None = None,
+              fallback: str = "error", viewport: tuple[float, float] | None = None, **model_options) -> TrajectoryMouse:
+        """Bind a trajectory mouse to a native Page owned by this Context.
+
+        Call synchronize once before moving. Adapters for the same Page share
+        position and serialization. Native mouse/Locator calls are not intercepted.
+        """
+        self._ensure_open()
+        if page.context is not self.raw:
+            raise ValueError("page must belong to this YSContext")
+        if page.is_closed():
+            raise ValueError("page is closed")
+        return TrajectoryMouse(page, model, fallback=fallback, viewport=viewport, **model_options)
+
+    async def new_page(self) -> Page:
+        async with self._gate:
+            self._ensure_open()
+            page = await self.raw.new_page()
+            await self._attach_diagnostic_page(page)
+            return page
+
+    async def close(self) -> None:
+        # Closing must interrupt a draining switch instead of waiting for its
+        # mutation lock/deadline. A separate lock preserves idempotent close.
+        async with self._close_gate:
+            if not self._closed:
+                self._closed = True
+                try:
+                    await complete(self.raw.close())
+                finally:
+                    self._on_closed()
+
+    async def __aenter__(self) -> YSContext:
+        self._ensure_open()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+
+class YSBrowser:
+    def __init__(self, executable_path: str | Path | None = None, *, headless: bool = False,
+                 server_gpu_profile: str | None = None, media_router: bool = True,
+                 context_gpu: bool = True, server_gpu_backend: str = "warp",
+                 default_proxy: ProxyConfig | Direct | None = None, args: list[str] | None = None,
+                 cdp_port: int | None = None):
+        self.executable_path = str(Path(executable_path).resolve() if executable_path is not None else get_browser_path())
+        if not Path(self.executable_path).is_file():
+            raise ConfigurationError("executable_path must point to an existing YSbrowser executable")
+        if server_gpu_profile is not None and (not isinstance(server_gpu_profile, str) or not re.fullmatch(r"[a-zA-Z0-9_-]+", server_gpu_profile)):
+            raise ConfigurationError("server_gpu_profile must be a GPU profile identifier")
+        if default_proxy is not None and not isinstance(default_proxy, (ProxyConfig, Direct)):
+            raise ConfigurationError("default_proxy must be ProxyConfig or Direct")
+        if type(context_gpu) is not bool or server_gpu_backend not in ("warp", "swiftshader"):
+            raise ConfigurationError("context_gpu must be boolean; server_gpu_backend must be warp or swiftshader")
+        self.context_gpu = context_gpu
+        if cdp_port is not None and (type(cdp_port) is not int or not 0 <= cdp_port <= 65535):
+            raise ConfigurationError("cdp_port must be None or an integer from 0 to 65535")
+        self.cdp_port = cdp_port
+        self._cdp_port: int | None = None
+        self.server_gpu_backend = server_gpu_backend
+        self.headless = headless
+        self.server_gpu_profile = server_gpu_profile
+        self.media_router = media_router
+        self.default_proxy = default_proxy if default_proxy is not None else Direct()
+        self.args = list(args or [])
+        managed = ("--disable-features", "--enable-features", "--proxy-", "--user-data-dir", "--remote-debugging", "--server-gpu-")
+        if any(not isinstance(arg, str) or arg.startswith(managed) for arg in self.args):
+            raise ConfigurationError("args must not override SDK feature policy, proxy, profile directory, debugging transport or GPU profile")
+        self._pw: Any = None
+        self._browser: Browser | None = None
+        self._cdp: CDPSession | None = None
+        self._contexts: dict[str, YSContext] = {}
+        self._creation_lock = asyncio.Lock()
+        self._lifecycle_lock = asyncio.Lock()
+        self._info: dict[str, Any] = {}
+        self._counter = 0
+        self._closing = False
+        self._unexpected_disconnect = False
+        self._disconnect_handlers: list[Any] = []
+        self._capabilities: BrowserCapabilities | None = None
+
+    @property
+    def capabilities(self) -> BrowserCapabilities:
+        if self._capabilities is None:
+            raise SDKError("BROWSER_NOT_RUNNING", "capabilities", "Start the browser before reading its capabilities")
+        return self._capabilities
+
+    def get_context(self, name: str) -> YSContext:
+        try:
+            return self._contexts[name]
+        except KeyError:
+            raise ConfigurationError("No open Context with this name") from None
+
+    async def close_context(self, name: str) -> None:
+        await self.get_context(name).close()
+
+    def on_disconnected(self, callback: Any) -> None:
+        if not callable(callback) or inspect.iscoroutinefunction(callback):
+            raise ConfigurationError("Disconnect callback must be a synchronous callable receiving one event dictionary")
+        self._disconnect_handlers.append(callback)
+
+    def _on_disconnected(self, *_: Any) -> None:
+        self._unexpected_disconnect = not self._closing
+        event = {"unexpected": self._unexpected_disconnect, "at": time.time() * 1000,
+                 "context_count": len(self._contexts)}
+        self._info["disconnect"] = event
+        for context in list(self._contexts.values()):
+            context._closed = True
+        for callback in tuple(self._disconnect_handlers):
+            try:
+                callback(dict(event))
+            except Exception as exc:
+                self._info["disconnect_callback_error"] = type(exc).__name__
+
+    @property
+    def raw(self) -> Browser:
+        if self._browser is None or not self._browser.is_connected():
+            raise SDKError("BROWSER_NOT_RUNNING", "browser", "Start the browser using async with or await start()")
+        return self._browser
+
+    @property
+    def contexts(self) -> tuple[YSContext, ...]:
+        return tuple(self._contexts.values())
+
+    @property
+    def cdp_endpoint(self) -> str | None:
+        """Optional loopback CDP endpoint for trusted integrations; None unless enabled."""
+        self.raw
+        return f"http://127.0.0.1:{self._cdp_port}" if self._cdp_port is not None else None
+
+    async def start(self) -> YSBrowser:
+        async with self._lifecycle_lock:
+            return await self._start_unlocked()
+
+    async def _start_unlocked(self) -> YSBrowser:
+        if self._browser is not None:
+            if not self._browser.is_connected():
+                raise SDKError("BROWSER_DISCONNECTED", "browser.start", "Close this instance before restarting it")
+            return self
+        self._info = runtime_info()
+        policy = launch_policy(self.media_router)
+        launch_args = ["--no-first-run", "--no-default-browser-check", *policy["args"], *self.args]
+        self._cdp_port = self.cdp_port
+        if self.cdp_port == 0:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+                probe.bind(("127.0.0.1", 0))
+                self._cdp_port = probe.getsockname()[1]
+        if self._cdp_port is not None:
+            launch_args.extend([f"--remote-debugging-port={self._cdp_port}", "--remote-debugging-address=127.0.0.1"])
+        if self.context_gpu:
+            launch_args.append("--server-gpu-contexts")
+        if self.context_gpu or self.server_gpu_profile is not None:
+            launch_args.append(f"--server-gpu-backend={self.server_gpu_backend}")
+        if self.server_gpu_profile is not None:
+            launch_args.append(f"--server-gpu-profile={self.server_gpu_profile}")
+        try:
+            self._pw = await acquire(async_playwright().start(), lambda pw: pw.stop())
+            self._browser = await acquire(self._pw.chromium.launch(executable_path=self.executable_path, headless=self.headless,
+                                                         chromium_sandbox=True, args=launch_args,
+                                                         ignore_default_args=policy["ignore_default_args"]), lambda browser: browser.close())
+            self._closing = False
+            self._unexpected_disconnect = False
+            self._browser.on("disconnected", self._on_disconnected)
+            self._cdp = await self._browser.new_browser_cdp_session()
+            try:
+                self._capabilities = BrowserCapabilities.from_cdp((await self._cdp.send("Browser.getCapabilities"))["capabilities"])
+            except Exception as exc:
+                raise CompatibilityError("BROWSER_CAPABILITIES_UNAVAILABLE", "browser.compatibility", "This SDK requires a browser with the capabilities/proxy-health patch", original_error=exc) from None
+            required = {"contextFingerprint", "contextProxy", "proxyCheck", "proxyGeneration"}
+            missing = sorted(required - set(self.capabilities.features))
+            if self.capabilities.protocol_version.split(".")[0] != "1" or missing:
+                raise CompatibilityError("BROWSER_CAPABILITIES_UNSUPPORTED", "browser.compatibility", "Browser protocol or capabilities are unsupported", details={"missing_features": missing})
+            self._info["capabilities"] = self.capabilities.to_dict()
+            self._info["browser"] = await self._cdp.send("Browser.getVersion")
+            self._info["context_gpu"] = self.context_gpu
+            self._info["server_gpu_backend"] = self.server_gpu_backend if self.context_gpu or self.server_gpu_profile is not None else None
+            self._info["media_router"] = self.media_router
+            self._info["server_gpu_profile"] = self.server_gpu_profile
+            self._closing = False
+            return self
+        except BaseException as exc:
+            await complete(self._close_unlocked())
+            if not isinstance(exc, Exception) or isinstance(exc, SDKError):
+                raise
+            raise SDKError("LAUNCH_FAILED", "browser.start", "Could not start the requested browser", original_error=exc) from None
+
+    async def new_context(self, *, name: str | None = None, fingerprint: FingerprintProfile | None = None,
+                          proxy: ProxyConfig | Direct | None = None, check: ProxyCheck | None = None,
+                          no_viewport: bool | None = None, config: ContextConfig | None = None,
+                          options: ContextOptions | None = None,
+                          storage_state: dict[str, Any] | str | Path | None = None) -> YSContext:
+        if config is not None and not isinstance(config, ContextConfig):
+            raise ConfigurationError("config must be ContextConfig")
+        selected_options = options if options is not None else (config.options if config else ContextOptions())
+        if not isinstance(selected_options, ContextOptions):
+            raise ConfigurationError('options must be ContextOptions')
+        selected_options = copy.deepcopy(selected_options)
+        native_options = selected_options.to_native()
+        if selected_options.viewport is not None and no_viewport is True:
+            raise ConfigurationError('viewport conflicts with no_viewport=True')
+        profile = fingerprint if fingerprint is not None else (config.fingerprint if config else FingerprintProfile())
+        selected_proxy = proxy if proxy is not None else (config.proxy if config else self.default_proxy)
+        if selected_options.client_certificates and not isinstance(selected_proxy, Direct):
+            raise ConfigurationError('Client-certificate Contexts currently support Direct only; proxy routing requires a separate adapter')
+        viewport = no_viewport if no_viewport is not None else (config.no_viewport if config else True)
+        if selected_options.viewport is not None and no_viewport is None:
+            viewport = False
+        if type(viewport) is not bool:
+            raise ConfigurationError("no_viewport must be boolean")
+        if viewport and selected_options.device_scale_factor is not None:
+            raise ConfigurationError('device_scale_factor requires options.viewport or no_viewport=False')
+        if not isinstance(profile, FingerprintProfile):
+            raise ConfigurationError("fingerprint must be FingerprintProfile")
+        profile.to_cdp()
+        if profile.server_gpu_profile is not None and not self.context_gpu and self.server_gpu_profile is None:
+            raise ConfigurationError("Context GPU profiles require context_gpu=True or a startup GPU profile")
+        async with self._lifecycle_lock, self._creation_lock:
+            if self._closing:
+                raise SDKError("BROWSER_CLOSING", "context.create", "Browser is closing")
+            browser = self.raw
+            assert self._cdp is not None
+            if name is None:
+                while name is None or name in self._contexts:
+                    self._counter += 1
+                    name = f"context-{self._counter}"
+            if not isinstance(name, str) or not name.strip() or name in self._contexts:
+                raise ConfigurationError("context name must be non-empty and unique among open contexts")
+            before = set((await self._cdp.send("Target.getBrowserContexts"))["browserContextIds"])
+            raw = await acquire(browser.new_context(no_viewport=viewport, **native_options), lambda context: context.close())
+            try:
+                after = set((await self._cdp.send("Target.getBrowserContexts"))["browserContextIds"])
+                ids = after - before
+                if len(ids) != 1:
+                    raise SDKError("CONTEXT_ID_AMBIGUOUS", "context.create", "Cannot map context ID; avoid concurrent creation through raw or external CDP clients")
+                context = YSContext(self, raw, ids.pop(), name)
+                context._options = selected_options
+                await context._apply_fingerprint(profile)
+                await context._apply_proxy(selected_proxy, check)
+                context._no_viewport = viewport
+                if selected_options.default_timeout_ms is not None:
+                    raw.set_default_timeout(selected_options.default_timeout_ms)
+                if selected_options.navigation_timeout_ms is not None:
+                    raw.set_default_navigation_timeout(selected_options.navigation_timeout_ms)
+                # Native restore may create temporary renderers: configure fingerprint first.
+                if storage_state is not None:
+                    await context.restore_storage_state(storage_state)
+                self._contexts[name] = context
+                return context
+            except BaseException:
+                await complete(raw.close())
+                raise
+
+    def diagnostics(self) -> dict[str, Any]:
+        # No custom argv, proxy credentials, seeds, URLs or user-supplied names.
+        return copy.deepcopy({**self._info, "context_count": len(self._contexts),
+                "connected": self._browser is not None and self._browser.is_connected(),
+                "contexts": [{"context_id": c.context_id} for c in self.contexts]})
+
+    async def close(self) -> None:
+        async with self._lifecycle_lock, self._creation_lock:
+            await complete(self._close_unlocked())
+
+    async def _close_unlocked(self) -> None:
+        self._closing = True
+        try:
+            if self._browser is not None:
+                await self._browser.close()
+        finally:
+            for context in list(self._contexts.values()):
+                context._closed = True
+            self._contexts.clear()
+            self._browser = None
+            self._cdp = None
+            self._capabilities = None
+            if self._pw is not None:
+                try:
+                    await self._pw.stop()
+                finally:
+                    self._pw = None
+
+    async def __aenter__(self) -> YSBrowser:
+        return await self.start()
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()