lithium-web 1.0__py3-none-any.whl

lithium/__init__.py

@@ -0,0 +1,8 @@
+from .client import Client, Config, AsyncClient
+from .response import Response, RequestInfo, NetworkLog
+from .session import Session
+from .dom import Dom
+from .element import Element
+
+__all__ = ["Client", "Config", "AsyncClient", "Response", "Session", "Dom", "Element", "RequestInfo", "NetworkLog"]
+__version__ = "1.0"

lithium/client.py

@@ -0,0 +1,436 @@
+import asyncio
+import json as jsonlib
+import time
+import uuid
+from urllib.parse import urlencode
+
+from .transport import connection
+from .response import Response, NetworkLog
+from .session import Session
+from .utils import LithiumError
+
+
+class Config:
+
+    def __init__(self, file=None, profile="chrome-windows", fingerprint=None, platform=None, browser=None, proxy=None,
+                 verify_ssl=True, trust_env=True, execute_scripts=False, js_timeout=10.0, timeout=30.0,
+                 solution=False, shared=True, verbose=False, binary=None,
+                 auto_location=None, auto_timezone=None, auto_currency=None, auto_language=None,
+                 virtual_gpu=True, canvas_noise=True, tls_spoof=None, http3=False,
+                 socket_timeout=None, storage_file=None,
+                 viewport_width=None, viewport_height=None, device_scale_factor=None, screen_color_depth=None,
+                 hardware_concurrency=None, device_memory=None, max_touch_points=None, do_not_track=None,
+                 audio_sample_rate=None, screenshot_width=None, screenshot_height=None,
+                 max_idle_conns=None, max_idle_conns_per_host=None, geo_url=None,
+                 proxies=None, max_redirects=0, ca_cert=None, client_cert=None, client_key=None,
+                 max_retries=0, retry_backoff=0.5, retry_codes=(429, 500, 502, 503, 504), auth=None):
+        data = {}
+        if file:
+            with open(file) as f:
+                data = jsonlib.load(f)
+
+        self.profile = data.get("profile", profile)
+        self.fingerprint = data.get("fingerprint", fingerprint)
+        self.platform = data.get("platform", platform)
+        self.browser = data.get("browser", browser)
+        self.proxy = data.get("proxy", proxy)
+        self.verify_ssl = data.get("verify_ssl", verify_ssl)
+        self.trust_env = data.get("trust_env", trust_env)
+        self.execute_scripts = data.get("execute_scripts", execute_scripts)
+        self.js_timeout = data.get("js_timeout", js_timeout)
+        self.timeout = data.get("timeout", timeout)
+        self.solution = data.get("solution", solution)
+        self.shared = data.get("shared", shared)
+        self.verbose = data.get("verbose", verbose)
+        self.binary = data.get("binary", binary)
+        self.auto_location = data.get("auto_location", auto_location)
+        self.auto_timezone = data.get("auto_timezone", auto_timezone)
+        self.auto_currency = data.get("auto_currency", auto_currency)
+        self.auto_language = data.get("auto_language", auto_language)
+        self.virtual_gpu = data.get("virtual_gpu", virtual_gpu)
+        self.canvas_noise = data.get("canvas_noise", canvas_noise)
+        self.tls_spoof = data.get("tls_spoof", tls_spoof)
+        self.http3 = data.get("http3", http3)
+        self.socket_timeout = data.get("socket_timeout", socket_timeout)
+        self.storage_file = data.get("storage_file", storage_file)
+        self.viewport_width = data.get("viewport_width", viewport_width)
+        self.viewport_height = data.get("viewport_height", viewport_height)
+        self.device_scale_factor = data.get("device_scale_factor", device_scale_factor)
+        self.screen_color_depth = data.get("screen_color_depth", screen_color_depth)
+        self.hardware_concurrency = data.get("hardware_concurrency", hardware_concurrency)
+        self.device_memory = data.get("device_memory", device_memory)
+        self.max_touch_points = data.get("max_touch_points", max_touch_points)
+        self.do_not_track = data.get("do_not_track", do_not_track)
+        self.audio_sample_rate = data.get("audio_sample_rate", audio_sample_rate)
+        self.screenshot_width = data.get("screenshot_width", screenshot_width)
+        self.screenshot_height = data.get("screenshot_height", screenshot_height)
+        self.max_idle_conns = data.get("max_idle_conns", max_idle_conns)
+        self.max_idle_conns_per_host = data.get("max_idle_conns_per_host", max_idle_conns_per_host)
+        self.geo_url = data.get("geo_url", geo_url)
+        self.proxies = data.get("proxies", proxies)
+        self.max_redirects = data.get("max_redirects", max_redirects)
+        self.ca_cert = data.get("ca_cert", ca_cert)
+        self.client_cert = data.get("client_cert", client_cert)
+        self.client_key = data.get("client_key", client_key)
+        self.max_retries = data.get("max_retries", max_retries)
+        self.retry_backoff = data.get("retry_backoff", retry_backoff)
+        self.retry_codes = data.get("retry_codes", retry_codes)
+        self.auth = data.get("auth", auth)
+        self._proxy_index = 0
+
+
+def build_body(data, json, headers):
+    if json is not None:
+        headers.setdefault("Content-Type", "application/json")
+        return jsonlib.dumps(json).encode()
+    if data is None:
+        return None
+    if isinstance(data, (bytes, bytearray)):
+        return bytes(data)
+    if isinstance(data, str):
+        return data.encode()
+    if isinstance(data, dict):
+        headers.setdefault("Content-Type", "application/x-www-form-urlencoded")
+        return urlencode(data, doseq=True).encode()
+    raise TypeError(f"unsupported type for data=: {type(data).__name__}, use bytes, str, dict, or json=")
+
+
+def build_multipart(data, files):
+    boundary = uuid.uuid4().hex
+    parts = []
+    for k, v in (data or {}).items():
+        parts.append(f'--{boundary}\r\nContent-Disposition: form-data; name="{k}"\r\n\r\n{v}\r\n'.encode())
+    for name, item in (files or {}).items():
+        if isinstance(item, tuple):
+            filename, content = item
+        else:
+            filename, content = name, item
+        if isinstance(content, str):
+            content = content.encode()
+        head = (f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"; filename="{filename}"\r\n'
+                f"Content-Type: application/octet-stream\r\n\r\n").encode()
+        parts.append(head + bytes(content) + b"\r\n")
+    parts.append(f"--{boundary}--\r\n".encode())
+    return b"".join(parts), boundary
+
+
+class Client:
+    """Undetected, requests + Selenium-style HTTP client.
+
+    Zero-config requests-style use:
+        client = Client()
+        resp = client.get("https://example.com")
+        print(resp.status_code, resp.text, resp.json())
+
+    Selenium-style page interaction (client.get returns a page):
+        page = client.get("https://example.com/login")
+        page.fill("#username", "alice")
+        page.fill("#password", "secret")
+        page.click("button[type=submit]")
+        page.wait_for("#dashboard")
+        print(page.text)
+        page.screenshot("dashboard.png")
+        for req in page.network.requests:
+            print(req.method, req.url)
+
+    Config can be passed as keywords directly:
+        client = Client(profile="chrome-windows")
+        client = Client(proxy="socks5://user:pass@host:1080", execute_scripts=True)
+    """
+
+    def __init__(self, config=None, **kwargs):
+        if config is not None and kwargs:
+            raise TypeError("pass either a Config object or keyword options, not both")
+        cfg = config or Config(**kwargs) or Config()
+        self._closed = False
+        self._timeout = cfg.timeout
+        self._cfg_proxies = cfg.proxies or []
+        self._proxy_index = 0
+        self._shot_w = getattr(cfg, "screenshot_width", None)
+        self._shot_h = getattr(cfg, "screenshot_height", None)
+        self.auth = cfg.auth
+        self.max_retries = cfg.max_retries
+        self.retry_backoff = cfg.retry_backoff
+        self.retry_codes = cfg.retry_codes or set()
+
+        self._conn = connection(binary=cfg.binary, verbose=cfg.verbose, solution=cfg.solution,
+                                 shared=cfg.shared, socket_timeout=cfg.socket_timeout)
+        self._conn.connect()
+
+        payload = {
+            "profile": cfg.profile,
+            "fingerprint": cfg.fingerprint or "",
+            "platform": cfg.platform or "",
+            "browser": cfg.browser or "",
+            "proxy": cfg.proxy or "",
+            "verify_ssl": cfg.verify_ssl,
+            "trust_env": cfg.trust_env,
+            "execute_scripts": cfg.execute_scripts,
+            "js_timeout": cfg.js_timeout,
+            "timeout": cfg.timeout,
+            "storage_file": cfg.storage_file or "",
+            "virtual_gpu": cfg.virtual_gpu,
+            "canvas_noise": cfg.canvas_noise,
+            "http3": cfg.http3,
+        }
+        if cfg.auto_location is not None:
+            payload["auto_location"] = cfg.auto_location
+        if cfg.auto_timezone is not None:
+            payload["auto_timezone"] = cfg.auto_timezone
+        if cfg.auto_currency is not None:
+            payload["auto_currency"] = cfg.auto_currency
+        if cfg.auto_language is not None:
+            payload["auto_language"] = cfg.auto_language
+        if cfg.tls_spoof is not None:
+            payload["tls_spoof"] = cfg.tls_spoof
+
+        for key, val in [
+            ("viewport_width", cfg.viewport_width),
+            ("viewport_height", cfg.viewport_height),
+            ("device_scale_factor", cfg.device_scale_factor),
+            ("screen_color_depth", cfg.screen_color_depth),
+            ("hardware_concurrency", cfg.hardware_concurrency),
+            ("device_memory", cfg.device_memory),
+            ("max_touch_points", cfg.max_touch_points),
+            ("audio_sample_rate", cfg.audio_sample_rate),
+            ("screenshot_width", cfg.screenshot_width),
+            ("screenshot_height", cfg.screenshot_height),
+            ("max_idle_conns", cfg.max_idle_conns),
+            ("max_idle_conns_per_host", cfg.max_idle_conns_per_host),
+            ("max_redirects", cfg.max_redirects),
+        ]:
+            if val is not None:
+                payload[key] = val
+        if cfg.geo_url is not None:
+            payload["geo_url"] = cfg.geo_url
+        for key, val in [("ca_cert", cfg.ca_cert), ("client_cert", cfg.client_cert), ("client_key", cfg.client_key)]:
+            if val:
+                payload[key] = val
+        if cfg.do_not_track is not None:
+            payload["do_not_track"] = cfg.do_not_track
+
+        result = self._conn.call("session.create", payload)
+        self._session = Session(self._conn, result["session_id"], cfg.profile, cfg.fingerprint)
+
+    def get(self, url, headers=None, timeout=None, proxy=None, fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        return self._request("GET", url, headers=headers, timeout=timeout, proxy=proxy,
+                              fingerprint=fingerprint, platform=platform, browser=browser, profile=profile, params=params, auth=auth)
+
+    def post(self, url, data=None, json=None, files=None, headers=None, timeout=None, proxy=None,
+              fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        headers = dict(headers or {})
+        if files is not None:
+            mpbody, boundary = build_multipart(data, files)
+            headers["Content-Type"] = f"multipart/form-data; boundary={boundary}"
+        else:
+            mpbody = build_body(data, json, headers)
+        return self._request("POST", url, headers=headers, body=mpbody, timeout=timeout, proxy=proxy,
+                              fingerprint=fingerprint, platform=platform, browser=browser, profile=profile, params=params, auth=auth)
+
+    def put(self, url, data=None, json=None, files=None, headers=None, timeout=None, proxy=None,
+             fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        headers = dict(headers or {})
+        if files is not None:
+            mpbody, boundary = build_multipart(data, files)
+            headers["Content-Type"] = f"multipart/form-data; boundary={boundary}"
+        else:
+            mpbody = build_body(data, json, headers)
+        return self._request("PUT", url, headers=headers, body=mpbody, timeout=timeout, proxy=proxy,
+                              fingerprint=fingerprint, platform=platform, browser=browser, profile=profile, params=params, auth=auth)
+
+    def patch(self, url, data=None, json=None, files=None, headers=None, timeout=None, proxy=None,
+               fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        headers = dict(headers or {})
+        if files is not None:
+            mpbody, boundary = build_multipart(data, files)
+            headers["Content-Type"] = f"multipart/form-data; boundary={boundary}"
+        else:
+            mpbody = build_body(data, json, headers)
+        return self._request("PATCH", url, headers=headers, body=mpbody, timeout=timeout, proxy=proxy,
+                              fingerprint=fingerprint, platform=platform, browser=browser, profile=profile, params=params, auth=auth)
+
+    def delete(self, url, headers=None, timeout=None, proxy=None, fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        return self._request("DELETE", url, headers=headers, timeout=timeout, proxy=proxy,
+                              fingerprint=fingerprint, platform=platform, browser=browser, profile=profile, params=params, auth=auth)
+
+    def head(self, url, headers=None, timeout=None, proxy=None, fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        return self._request("HEAD", url, headers=headers, timeout=timeout, proxy=proxy,
+                              fingerprint=fingerprint, platform=platform, browser=browser, profile=profile, params=params, auth=auth)
+
+    def options(self, url, headers=None, timeout=None, proxy=None, fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        return self._request("OPTIONS", url, headers=headers, timeout=timeout, proxy=proxy,
+                              fingerprint=fingerprint, platform=platform, browser=browser, profile=profile, params=params, auth=auth)
+
+    def _request(self, method, url, headers=None, body=None, timeout=None, proxy=None,
+                  fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        if self._closed:
+            raise LithiumError("this client is closed, create a new Client() to make more requests")
+
+        if proxy is None and self._cfg_proxies:
+            proxy = self._next_proxy()
+
+        if params:
+            url = url + ("&" if "?" in url else "?") + urlencode(params, doseq=True)
+
+        headers = dict(headers or {})
+        credentials = auth or self.auth
+        if credentials:
+            import base64
+            raw = f"{credentials[0]}:{credentials[1]}".encode()
+            headers["Authorization"] = "Basic " + base64.b64encode(raw).decode()
+
+        req_params = {
+            "session_id": self._session.id,
+            "method": method,
+            "url": url,
+            "headers": headers,
+            "timeout": timeout if timeout is not None else self._timeout,
+            "proxy": proxy or "",
+            "fingerprint": fingerprint or "",
+            "platform": platform or "",
+            "browser": browser or "",
+            "profile": profile or "",
+        }
+        if body is not None:
+            req_params["body"] = body
+
+        attempts = self.max_retries + 1
+        for attempt in range(attempts):
+            data = self._conn.call("http.fetch", req_params)
+            resp = Response(data, conn=self._conn, session_id=self._session.id,
+                            screenshot_width=self._shot_w, screenshot_height=self._shot_h)
+            if attempt < self.max_retries and resp.status_code in self.retry_codes:
+                time.sleep(self.retry_backoff * (2 ** attempt))
+                continue
+            return resp
+        return resp
+
+    def request(self, method, url, **kwargs):
+        method = method.upper()
+        if method == "GET":
+            return self.get(url, **kwargs)
+        if method in ("POST", "PUT", "PATCH"):
+            return getattr(self, method.lower())(url, **kwargs)
+        if method == "DELETE":
+            return self.delete(url, **kwargs)
+        if method == "HEAD":
+            return self.head(url, **kwargs)
+        if method == "OPTIONS":
+            return self.options(url, **kwargs)
+        raise LithiumError(f"unsupported method: {method}")
+
+    def map(self, urls, method="GET", max_workers=8, **kwargs):
+        from concurrent.futures import ThreadPoolExecutor
+        with ThreadPoolExecutor(max_workers=max_workers) as pool:
+            return list(pool.map(lambda u: self.request(method, u, **kwargs), urls))
+
+    def cookies(self, url):
+        data = self._conn.call("session.cookies", {"session_id": self._session.id, "url": url})
+        return {c["name"]: c["value"] for c in data.get("cookies", [])}
+
+    def clear_cookies(self):
+        self._session.clear_cookies()
+
+    def _next_proxy(self):
+        pool = self._cfg_proxies
+        p = pool[self._proxy_index % len(pool)]
+        self._proxy_index += 1
+        return p
+
+    def stream_to_file(self, url, path, method="GET", headers=None, body=None, timeout=None,
+                       proxy=None, fingerprint=None, platform=None, browser=None, profile=None, params=None, auth=None):
+        if self._closed:
+            raise LithiumError("this client is closed, create a new Client() to make more requests")
+        if proxy is None and self._cfg_proxies:
+            proxy = self._next_proxy()
+        params = {
+            "session_id": self._session.id,
+            "method": method,
+            "url": url,
+            "headers": headers or {},
+            "timeout": timeout if timeout is not None else self._timeout,
+            "proxy": proxy or "",
+            "fingerprint": fingerprint or "",
+            "platform": platform or "",
+            "browser": browser or "",
+            "profile": profile or "",
+            "path": path,
+        }
+        if body is not None:
+            params["body"] = body
+        data = self._conn.call("http.download", params)
+        return Response(data, conn=self._conn, session_id=self._session.id)
+
+    def download(self, url, path, timeout=None, proxy=None):
+        response = self.get(url, timeout=timeout, proxy=proxy)
+        with open(path, "wb") as f:
+            f.write(response.content)
+        return path
+
+    @property
+    def network(self):
+        if self._closed:
+            raise LithiumError("this client is closed, create a new Client() to inspect network activity")
+        data = self._conn.call("network.requests", {"session_id": self._session.id})
+        return NetworkLog(data.get("requests", []))
+
+    def close(self):
+        if self._closed:
+            return
+        self._closed = True
+        try:
+            self._session.close()
+        finally:
+            self._conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+class AsyncClient:
+
+    def __init__(self, config=None, **kwargs):
+        self._client = Client(config=config, **kwargs)
+
+    async def get(self, *a, **k):
+        return await asyncio.to_thread(self._client.get, *a, **k)
+
+    async def post(self, *a, **k):
+        return await asyncio.to_thread(self._client.post, *a, **k)
+
+    async def put(self, *a, **k):
+        return await asyncio.to_thread(self._client.put, *a, **k)
+
+    async def patch(self, *a, **k):
+        return await asyncio.to_thread(self._client.patch, *a, **k)
+
+    async def delete(self, *a, **k):
+        return await asyncio.to_thread(self._client.delete, *a, **k)
+
+    async def head(self, *a, **k):
+        return await asyncio.to_thread(self._client.head, *a, **k)
+
+    async def options(self, *a, **k):
+        return await asyncio.to_thread(self._client.options, *a, **k)
+
+    async def stream_to_file(self, *a, **k):
+        return await asyncio.to_thread(self._client.stream_to_file, *a, **k)
+
+    async def download(self, *a, **k):
+        return await asyncio.to_thread(self._client.download, *a, **k)
+
+    async def close(self):
+        self._client.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()
+
+    @property
+    def network(self):
+        return self._client.network

lithium/diagnostics.py

@@ -0,0 +1,214 @@
+import socket
+import ssl
+from urllib.parse import urlparse
+
+
+catalog = {
+    "timeout": {
+        "explain": "the server did not respond before the timeout elapsed",
+        "fix": [
+            "increase the timeout: client.get(url, timeout=60)",
+            "check if the target server is slow or overloaded right now",
+            "confirm your network can reach the host at all",
+        ],
+    },
+    "dns_failure": {
+        "explain": "the hostname could not be resolved to an ip address",
+        "fix": [
+            "check the url for typos",
+            "confirm your dns resolver is working (try: nslookup <host>)",
+        ],
+    },
+    "connection_refused": {
+        "explain": "the remote host actively refused the connection",
+        "fix": [
+            "confirm the port is correct and the service is actually running",
+            "check firewall rules on the target host",
+        ],
+    },
+    "connection_reset": {
+        "explain": "the connection was closed abruptly by the remote server",
+        "fix": [
+            "retry the request, this is often transient",
+            "check if the server is rate-limiting or blocking this client",
+        ],
+    },
+    "tls_error": {
+        "explain": "the tls handshake or certificate verification failed",
+        "fix": [
+            "check if the site's certificate is valid or expired",
+            "confirm your system clock is correct (a bad clock breaks tls)",
+        ],
+    },
+    "canceled": {
+        "explain": "the request was canceled before it completed",
+        "fix": ["check for a manual cancellation or a short timeout upstream"],
+    },
+    "invalid_method": {
+        "explain": "the http method given isn't supported",
+        "fix": ["use one of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS"],
+    },
+    "empty_url": {
+        "explain": "no url was provided to the request",
+        "fix": ["pass a non-empty url, e.g. client.get('https://example.com')"],
+    },
+    "session_not_found": {
+        "explain": "the session backing this client no longer exists on the runtime",
+        "fix": ["create a new Client() instance, the previous one was likely closed"],
+    },
+    "page_not_found": {
+        "explain": "the page (parsed dom) referenced no longer exists on the runtime",
+        "fix": ["re-fetch the page with client.get(url) before querying its dom again"],
+    },
+    "node_not_found": {
+        "explain": "the dom element referenced no longer exists, likely removed",
+        "fix": ["re-query the element with page.dom.query(...) before using it again"],
+    },
+    "unknown_op": {
+        "explain": "the python client sent an operation the go runtime doesn't recognize",
+        "fix": ["this usually means python/lithium and the go binary are out of sync, rebuild the go binary"],
+    },
+    "invalid_proxy": {
+        "explain": "the proxy url couldn't be parsed",
+        "fix": [
+            "check the proxy url format, e.g. socks5://user:pass@host:port",
+            "supported schemes: http, https, socks4, socks4a, socks5, socks5h",
+        ],
+    },
+    "unsupported_proxy_scheme": {
+        "explain": "the proxy url's scheme isn't one lithium understands",
+        "fix": ["use one of: http, https, socks4, socks4a, socks5, socks5h"],
+    },
+    "proxy_setup_failed": {
+        "explain": "the proxy dialer couldn't be constructed",
+        "fix": ["check the proxy host/port and credentials are correct"],
+    },
+    "proxy_connect_failed": {
+        "explain": "the proxy server rejected the connection request",
+        "fix": [
+            "confirm the proxy is online and accepting connections",
+            "double check proxy credentials if the proxy requires auth",
+        ],
+    },
+    "proxy_resolve_failed": {
+        "explain": "the target hostname couldn't be resolved for a socks4 proxy",
+        "fix": ["socks4 needs the client to resolve dns itself - try socks4a to let the proxy resolve it instead"],
+    },
+    "proxy_unsupported_address": {
+        "explain": "socks4 only supports ipv4 targets",
+        "fix": ["use socks5 or socks5h if the target requires ipv6"],
+    },
+    "js_error": {
+        "explain": "the javascript engine raised an error while running the script",
+        "fix": [
+            "check the error message above for the js exception detail",
+            "if the script never finished, it may have hit the execution timeout (10s default)",
+        ],
+    },
+    "geo_lookup_failed": {
+        "explain": "auto_timezone/auto_currency/auto_language couldn't resolve geo info for the current outbound ip",
+        "fix": [
+            "check the proxy (if any) actually has working outbound connectivity",
+            "the lookup service may be rate limiting - it's capped around 45 requests/minute",
+        ],
+    },
+    "tls_h2_unsupported": {
+        "explain": "the spoofed tls handshake negotiated http/2 with the server, which this transport can't speak yet over a spoofed connection - this is a safety net catching an edge case, not expected in normal use",
+        "fix": [
+            "retry the request, this can be transient depending on the target server",
+            "set tls_spoof=False on Config to fall back to plain (non-spoofed) tls for this target",
+            "if this keeps happening for a specific site, please report it",
+        ],
+    },
+    "socket_timeout": {
+        "explain": "the go runtime didn't respond within Config(socket_timeout=...) seconds",
+        "fix": [
+            "increase socket_timeout if this call is legitimately slow (e.g. a long execute_script)",
+            "rerun with Client(Config(verbose=True)) to see whether the go side is stuck or just slow",
+        ],
+    },
+    "connection_lost": {
+        "explain": "the connection to the go runtime dropped mid-call, usually because the runtime process exited or crashed",
+        "fix": [
+            "rerun with Client(Config(verbose=True)) to see go-side logs on stderr",
+            "check the runtime binary is present and executable (LITHIUM_BINARY if set)",
+            "if using a shared runtime, the process may have been killed externally",
+        ],
+    },
+    "not_a_form": {
+        "explain": "submit() was called on an element that isn't a <form> and has no ancestor <form>",
+        "fix": ["call submit() on the form itself, or on a button/input inside one"],
+    },
+    "option_not_found": {
+        "explain": "select_option() was given a value that doesn't match any <option> in the <select>",
+        "fix": ["check the exact value or text of the <option> elements (el.html can help here)"],
+    },
+}
+
+
+def humanize(code: str) -> str:
+    return code.replace("_", " ").strip().capitalize()
+
+
+def live_probe(url: str):
+    findings = []
+    try:
+        parsed = urlparse(url)
+        host = parsed.hostname
+        port = parsed.port or (443 if parsed.scheme == "https" else 80)
+    except Exception:
+        return ["could not parse url to run live diagnostics"]
+
+    if not host:
+        return ["url has no hostname to probe"]
+
+    try:
+        socket.getaddrinfo(host, port)
+        findings.append(f"dns resolves for {host}")
+    except socket.gaierror as e:
+        findings.append(f"dns resolution failed for {host}: {e}")
+        return findings
+
+    try:
+        with socket.create_connection((host, port), timeout=5):
+            findings.append(f"tcp connect to {host}:{port} succeeded")
+    except OSError as e:
+        findings.append(f"tcp connect to {host}:{port} failed: {e}")
+        return findings
+
+    if parsed.scheme == "https":
+        try:
+            ctx = ssl.create_default_context()
+            with socket.create_connection((host, port), timeout=5) as sock:
+                with ctx.wrap_socket(sock, server_hostname=host):
+                    findings.append("tls handshake succeeded")
+        except Exception as e:
+            findings.append(f"tls handshake failed: {e}")
+
+    return findings
+
+
+def build_solution(code: str, url=None, live=False) -> str:
+    entry = catalog.get(code)
+    lines = [f"[lithium diagnostics] error code: {code}"]
+
+    if entry:
+        lines.append(f"likely cause: {entry['explain']}")
+        lines.append("suggested fixes:")
+        for fix in entry["fix"]:
+            lines.append(f"  - {fix}")
+    else:
+        lines.append(f"likely cause: {humanize(code)} (not in the catalog yet, generic guidance below)")
+        lines.append("suggested fixes:")
+        lines.append("  - check the error message above for specifics")
+        lines.append("  - retry the request, this may be transient")
+        lines.append("  - rerun with Client(verbose=True) to see go-side logs")
+
+    if live and url:
+        findings = live_probe(url)
+        if findings:
+            lines.append("live diagnostics:")
+            for f in findings:
+                lines.append(f"  - {f}")
+
+    return "\n".join(lines)