dataapp_crawler 0.1.0__py3-none-any.whl

dataapp_crawler/errors.py

@@ -0,0 +1,184 @@
+"""Small error vocabulary; messages never include upstream exception text or credentials."""
+
+import re
+from typing import Any, TypedDict
+
+import httpx
+
+_BROWSER_ERROR_CODES = frozenset(
+    {
+        "ERR_PROXY_CONNECTION_FAILED", "ERR_TUNNEL_CONNECTION_FAILED",
+        "ERR_INVALID_AUTH_CREDENTIALS", "ERR_PROXY_AUTH_UNSUPPORTED", "ERR_NO_SUPPORTED_PROXIES",
+        "ERR_CONNECTION_RESET", "ERR_CONNECTION_CLOSED", "ERR_CONNECTION_REFUSED",
+        "ERR_NAME_NOT_RESOLVED", "ERR_CERT_AUTHORITY_INVALID", "ERR_PROXY_CERTIFICATE_INVALID",
+        "ERR_TIMED_OUT", "ERR_ABORTED",
+        "ERR_HTTP_RESPONSE_CODE_FAILURE",
+    }
+)
+_BROWSER_ERROR = re.compile(
+    r"net::(" + "|".join(sorted(_BROWSER_ERROR_CODES)) + r")(?![A-Za-z0-9_])"
+)
+
+_HTTP_ERROR_TYPES: tuple[tuple[type[httpx.HTTPError], str], ...] = (
+    (httpx.ConnectTimeout, "HTTPX_CONNECT_TIMEOUT"),
+    (httpx.ReadTimeout, "HTTPX_READ_TIMEOUT"),
+    (httpx.WriteTimeout, "HTTPX_WRITE_TIMEOUT"),
+    (httpx.PoolTimeout, "HTTPX_POOL_TIMEOUT"),
+    (httpx.ConnectError, "HTTPX_CONNECT_ERROR"),
+    (httpx.ReadError, "HTTPX_READ_ERROR"),
+    (httpx.WriteError, "HTTPX_WRITE_ERROR"),
+    (httpx.CloseError, "HTTPX_CLOSE_ERROR"),
+    (httpx.ProxyError, "HTTPX_PROXY_ERROR"),
+    (httpx.LocalProtocolError, "HTTPX_LOCAL_PROTOCOL_ERROR"),
+    (httpx.RemoteProtocolError, "HTTPX_REMOTE_PROTOCOL_ERROR"),
+    (httpx.DecodingError, "HTTPX_DECODING_ERROR"),
+    (httpx.TooManyRedirects, "HTTPX_TOO_MANY_REDIRECTS"),
+    (httpx.UnsupportedProtocol, "HTTPX_UNSUPPORTED_PROTOCOL"),
+    (httpx.HTTPStatusError, "HTTPX_HTTP_STATUS_ERROR"),
+    (httpx.TimeoutException, "HTTPX_TIMEOUT"),
+    (httpx.NetworkError, "HTTPX_NETWORK_ERROR"),
+    (httpx.ProtocolError, "HTTPX_PROTOCOL_ERROR"),
+    (httpx.TransportError, "HTTPX_TRANSPORT_ERROR"),
+    (httpx.RequestError, "HTTPX_REQUEST_ERROR"),
+    (httpx.HTTPError, "HTTPX_HTTP_ERROR"),
+)
+_HTTP_ERROR_CODES = frozenset(code for _, code in _HTTP_ERROR_TYPES) | {
+    "HTTP_REDIRECT_LIMIT_REACHED"
+}
+
+
+class NetworkDiagnosticsSummary(TypedDict):
+    events: list[dict[str, Any]]
+    events_dropped: int
+    main_document_status: int | None
+
+
+def browser_error_code(error: Exception | str) -> str | None:
+    """Keep only fixed Chromium codes; never retain arbitrary upstream error text."""
+    code = getattr(error, "browser_error_code", None)
+    if isinstance(code, str) and code in _BROWSER_ERROR_CODES:
+        return code
+    match = _BROWSER_ERROR.search(str(error))
+    return match.group(1) if match else None
+
+
+def http_error_code(error: Exception) -> str | None:
+    """Map HTTPX exception types to fixed codes without inspecting exception text."""
+    code = getattr(error, "http_error_code", None)
+    if isinstance(code, str) and code in _HTTP_ERROR_CODES:
+        return code
+    return next(
+        (code for error_type, code in _HTTP_ERROR_TYPES if isinstance(error, error_type)),
+        None,
+    )
+
+
+class CrawlerError(Exception):
+    kind = "crawler"
+
+
+class FetchError(CrawlerError):
+    kind = "network"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retryable: bool = False,
+        phase: str | None = None,
+        browser_error_code: str | None = None,
+        http_error_code: str | None = None,
+        network_diagnostics: NetworkDiagnosticsSummary | None = None,
+        main_document_status: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.retryable = retryable
+        self.phase = phase
+        self.retry_events: list[dict[str, Any]] = []
+        self.browser_diagnostics: dict[str, Any] = {}
+        self.network_diagnostics = network_diagnostics
+        self.main_document_status = (
+            main_document_status
+            if isinstance(main_document_status, int)
+            and not isinstance(main_document_status, bool)
+            and 100 <= main_document_status <= 599
+            else None
+        )
+        self.browser_error_code = (
+            browser_error_code
+            if isinstance(browser_error_code, str) and browser_error_code in _BROWSER_ERROR_CODES
+            else None
+        )
+        self.http_error_code = (
+            http_error_code
+            if isinstance(http_error_code, str) and http_error_code in _HTTP_ERROR_CODES
+            else None
+        )
+
+
+class ResponseTooLarge(FetchError):
+    kind = "response_too_large"
+
+
+class ConfigurationError(CrawlerError):
+    kind = "configuration"
+
+
+class CrawlCancelled(CrawlerError):
+    kind = "cancelled"
+
+
+class LimitReached(CrawlerError):
+    kind = "limit"
+
+
+class QueueFull(CrawlerError):
+    kind = "queue_full"
+
+
+class ProcessingError(CrawlerError):
+    kind = "process"
+    phase = "process"
+
+    def __init__(
+        self, message: str, *, capture: Any = None, process_error_code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.capture = capture
+        self.process_error_code = (
+            process_error_code
+            if isinstance(process_error_code, str) and process_error_code in _PROCESS_ERROR_CODES
+            else None
+        )
+
+
+_PROCESS_ERROR_TYPES: tuple[tuple[type[Exception], str], ...] = (
+    (ResponseTooLarge, "PROCESS_RESPONSE_TOO_LARGE"),
+    (FetchError, "PROCESS_FETCH_ERROR"),
+    (TimeoutError, "PROCESS_TIMEOUT"),
+    (KeyError, "PROCESS_KEY_ERROR"),
+    (IndexError, "PROCESS_INDEX_ERROR"),
+    (AttributeError, "PROCESS_ATTRIBUTE_ERROR"),
+    (TypeError, "PROCESS_TYPE_ERROR"),
+    (ValueError, "PROCESS_VALUE_ERROR"),
+    (AssertionError, "PROCESS_ASSERTION_ERROR"),
+)
+_PROCESS_ERROR_CODES = frozenset(code for _, code in _PROCESS_ERROR_TYPES) | {"PROCESS_ERROR"}
+
+
+def process_error_code(error: Exception) -> str:
+    """Describe a callback failure using fixed codes, without its message or traceback."""
+    if (
+        isinstance(error, ProcessingError)
+        and isinstance(error.process_error_code, str)
+        and error.process_error_code in _PROCESS_ERROR_CODES
+    ):
+        return error.process_error_code
+    # Optional browser libraries define their own TimeoutError. No provider import
+    # or arbitrary exception class name is needed in the public diagnostic.
+    if type(error).__name__ == "TimeoutError":
+        return "PROCESS_TIMEOUT"
+    return next(
+        (code for error_type, code in _PROCESS_ERROR_TYPES if isinstance(error, error_type)),
+        "PROCESS_ERROR",
+    )

dataapp_crawler/http.py

@@ -0,0 +1,223 @@
+"""HTTPX session with bounded reads and explicit per-origin redirect handling."""
+
+from __future__ import annotations
+
+import http.cookiejar
+import time
+from collections.abc import Callable
+
+import httpx
+
+from .context import CrawlContext, SiteGate
+from .cookies import (
+    cookies_from_jar,
+    is_partitioned_jar_cookie,
+    replace_jar,
+    validate_shareable_cookies,
+)
+from .errors import ConfigurationError, FetchError, ResponseTooLarge, http_error_code
+from .models import CaptureResult, Identity, Limits, Request, origin, safe_url
+
+
+class _BorrowedAsyncTransport(httpx.AsyncBaseTransport):
+    """Let multiple short-lived clients share one caller-owned transport."""
+
+    def __init__(self, transport: httpx.AsyncBaseTransport) -> None:
+        self._transport = transport
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        return await self._transport.handle_async_request(request)
+
+    async def aclose(self) -> None:
+        # The Crawler closes the injected transport once after all generations retire.
+        return None
+
+
+class HttpSession:
+    def __init__(
+        self,
+        limits: Limits,
+        identity: Identity,
+        *,
+        proxy_url: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        close_transport: bool = True,
+        reject_partitioned: bool = False,
+    ) -> None:
+        self.limits = limits
+        self.identity = identity
+        self.reject_partitioned = reject_partitioned
+        cookies = [*(identity.storage_state or {}).get("cookies", []), *identity.cookies]
+        if reject_partitioned:
+            validate_shareable_cookies(cookies)
+        client_transport = (
+            _BorrowedAsyncTransport(transport)
+            if transport is not None and not close_transport
+            else transport
+        )
+        self.client = httpx.AsyncClient(
+            timeout=httpx.Timeout(limits.request_timeout),
+            follow_redirects=False,
+            trust_env=False,
+            proxy=proxy_url,
+            transport=client_transport,
+        )
+        self.client.cookies.jar.set_policy(
+            http.cookiejar.DefaultCookiePolicy(
+                strict_ns_domain=http.cookiejar.DefaultCookiePolicy.DomainStrictNonDomain
+            )
+        )
+        # CookieJar preserves Secure, path, domain, expiry and supported metadata.
+        replace_jar(
+            self.client.cookies.jar,
+            cookies,
+            ignore_partitioned=not reject_partitioned,
+        )
+
+    async def close(self) -> None:
+        await self.client.aclose()
+
+    def export_cookies(self) -> list[dict[str, object]]:
+        """Return the current jar as browser-compatible, non-header cookie records."""
+        return cookies_from_jar(self.client.cookies.jar)
+
+    def replace_cookies(self, cookies: list[dict[str, object]]) -> None:
+        """Replace this session's jar from a canonical session snapshot."""
+        replace_jar(self.client.cookies.jar, cookies)
+
+    async def fetch(
+        self, request: Request, context: CrawlContext, gate: Callable[[str], SiteGate]
+    ) -> CaptureResult:
+        initial_origin = origin(request.url)
+        headers = {**request.headers, **self.identity.headers_for(request.url)}
+        current = self.client.build_request(
+            request.method,
+            request.url,
+            params=request.params,
+            content=request.content,
+            json=request.json,
+            headers=headers,
+        )
+        # HTTPX build_request merges cookies through a fresh CookieJar. Reapply the
+        # session jar's host-only policy instead of inheriting that copy's policy.
+        current.headers.pop("cookie", None)
+        self.client.cookies.set_cookie_header(current)
+        for name, value in request.headers.items():
+            if name.lower() == "cookie":
+                current.headers[name] = value
+        started = time.monotonic()
+        for redirects in range(self.limits.max_redirects + 1):
+            context.reserve_request()
+            response: httpx.Response | None = None
+            failure: FetchError | None = None
+            try:
+                async with gate(request.site_key or origin(str(current.url))):
+                    response = await self.client.send(current, stream=True, follow_redirects=False)
+                    self._narrow_response_cookies(response)
+                    body = bytearray()
+                    async for chunk in response.aiter_bytes():
+                        if len(body) + len(chunk) > self.limits.max_response_bytes:
+                            raise ResponseTooLarge("Response exceeds configured byte limit")
+                        body.extend(chunk)
+                next_request = response.next_request
+                if next_request is None:
+                    return CaptureResult(
+                        request,
+                        str(response.url),
+                        response.status_code,
+                        dict(response.headers),
+                        bytes(body),
+                        elapsed=time.monotonic() - started,
+                        diagnostics={"url": safe_url(str(response.url)), "mode": "http"},
+                    )
+                if redirects == self.limits.max_redirects:
+                    raise FetchError(
+                        "Redirect limit reached",
+                        phase="http_redirect",
+                        http_error_code="HTTP_REDIRECT_LIMIT_REACHED",
+                        main_document_status=response.status_code,
+                    )
+                # Remove all caller custom headers on an origin change. Rebuild Cookie from
+                # the jar; add website credentials only for the next URL's explicit origin.
+                next_origin = origin(str(next_request.url))
+                target_host = httpx.Request("GET", next_request.url).headers["host"]
+                for name in set(request.headers) | {
+                    k for values in self.identity.headers.values() for k in values
+                }:
+                    next_request.headers.pop(name, None)
+                for name in ("authorization", "cookie", "proxy-authorization", "host"):
+                    next_request.headers.pop(name, None)
+                self.client.cookies.set_cookie_header(next_request)
+                if next_origin == initial_origin:
+                    next_request.headers.update(request.headers)
+                next_request.headers.update(self.identity.headers_for(str(next_request.url)))
+                if next_origin != initial_origin or "host" not in next_request.headers:
+                    next_request.headers["host"] = target_host
+                current = next_request
+            except (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError) as exc:
+                failure = FetchError(
+                    "HTTP transport failed",
+                    retryable=True,
+                    phase="http_transport",
+                    http_error_code=http_error_code(exc),
+                )
+            except httpx.HTTPError as exc:
+                failure = FetchError(
+                    "HTTP request failed",
+                    phase="http_request",
+                    http_error_code=http_error_code(exc),
+                )
+            finally:
+                if response is not None:
+                    await response.aclose()
+            if failure is not None:
+                # Raise after leaving the HTTPX handler so the raw exception (which can
+                # contain URLs, headers, or proxy credentials) is not retained as context.
+                raise failure
+        raise FetchError(
+            "Redirect limit reached",
+            phase="http_redirect",
+            http_error_code="HTTP_REDIRECT_LIMIT_REACHED",
+        )
+
+    def _narrow_response_cookies(self, response: httpx.Response) -> None:
+        """Keep accepted response cookies, but scope them to the setting host."""
+        host = response.url.host
+        for cookie in response.cookies.jar:
+            try:
+                self.client.cookies.jar.clear(cookie.domain, cookie.path, cookie.name)
+            except KeyError:
+                pass
+            try:
+                self.client.cookies.jar.clear(host, cookie.path, cookie.name)
+            except KeyError:
+                pass
+            if is_partitioned_jar_cookie(cookie):
+                if self.reject_partitioned:
+                    raise ConfigurationError(
+                        "Partitioned cookies cannot be shared across engines"
+                    )
+                continue
+            if cookie.expires is not None and cookie.expires <= time.time():
+                continue
+            self.client.cookies.jar.set_cookie(
+                http.cookiejar.Cookie(
+                    version=cookie.version,
+                    name=cookie.name,
+                    value=cookie.value,
+                    port=cookie.port,
+                    port_specified=cookie.port_specified,
+                    domain=host,
+                    domain_specified=False,
+                    domain_initial_dot=False,
+                    path=cookie.path,
+                    path_specified=cookie.path_specified,
+                    secure=cookie.secure,
+                    expires=cookie.expires,
+                    discard=cookie.discard,
+                    comment=cookie.comment,
+                    comment_url=cookie.comment_url,
+                    rest=dict(getattr(cookie, "_rest", {})),
+                    rfc2109=cookie.rfc2109,
+                )
+            )

dataapp_crawler/images.py

@@ -0,0 +1,267 @@
+"""Capture the currently rendered image without fetching its source URL again."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import binascii
+import hashlib
+import math
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from .errors import ConfigurationError, FetchError, ResponseTooLarge
+
+
+@dataclass(frozen=True, slots=True)
+class CapturedImage:
+    """Private PNG bytes with encodings accepted by solver and vision resources.
+
+    Treat ``image_body`` and ``data_url`` as sensitive page content. They are not
+    included in the representation. A matching hash identifies captured bytes,
+    not a guarantee that the website still accepts the same challenge.
+    """
+
+    _png: bytes = field(repr=False)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self._png, bytes) or not self._png.startswith(b"\x89PNG\r\n\x1a\n"):
+            raise ConfigurationError("Captured image must contain PNG bytes")
+
+    @property
+    def image_body(self) -> str:
+        """Return base64 PNG for ``solve_captcha(image_body=...)``."""
+        return base64.b64encode(self._png).decode("ascii")
+
+    @property
+    def data_url(self) -> str:
+        """Return an inline PNG URL for a model's ``image_url`` content part."""
+        return "data:image/png;base64," + self.image_body
+
+    @property
+    def sha256(self) -> str:
+        """Return a content fingerprint without exposing the image."""
+        return hashlib.sha256(self._png).hexdigest()
+
+
+async def capture_image(
+    locator: Any,
+    *,
+    timeout: float = 10_000,
+    max_bytes: int = 50_000,
+    source: Literal["rendered", "loaded_image"] = "rendered",
+) -> CapturedImage:
+    """Capture one native Playwright Locator without fetching its source again.
+
+    ``timeout`` uses Playwright milliseconds and bounds capture work. Closing a
+    CDP session gets up to 250 additional milliseconds after timeout or caller
+    cancellation; the original TimeoutError or cancellation is then preserved.
+    Wrap this coroutine in ``context.run(...)`` to share a crawl's cancellation
+    and duration budget.
+    The default size fits Resource Proxy's image-to-text task limit. A vision
+    model may accept larger images; opt into a larger ``max_bytes`` explicitly.
+
+    The default ``rendered`` source captures a visible element. On Chromium it
+    uses a clipped CDP screenshot to avoid Playwright's document-font wait, then
+    falls back to the native Locator screenshot when CDP is unavailable. A
+    zero-size element is rejected instead of silently changing capture semantics.
+
+    ``loaded_image`` explicitly copies pixels from an already loaded ``IMG`` via
+    canvas. It can capture an intentionally hidden image, but may fail for a
+    cross-origin image whose pixels are protected by the browser. Neither source
+    requests the element's ``src`` URL. Capture again only when starting a new
+    logical task.
+    """
+    if (
+        isinstance(timeout, bool)
+        or not isinstance(timeout, (int, float))
+        or not math.isfinite(timeout)
+        or timeout <= 0
+    ):
+        raise ConfigurationError("Image capture timeout must be finite and positive")
+    if isinstance(max_bytes, bool) or not isinstance(max_bytes, int) or max_bytes <= 0:
+        raise ConfigurationError("Image capture max_bytes must be a positive integer")
+    if not isinstance(source, str) or source not in {"rendered", "loaded_image"}:
+        raise ConfigurationError("Image capture source must be rendered or loaded_image")
+    deadline = asyncio.get_running_loop().time() + timeout / 1000
+    try:
+        async with asyncio.timeout_at(deadline):
+            if source == "loaded_image":
+                png = await _capture_loaded_image(locator, max_bytes=max_bytes)
+            else:
+                png = await _capture_rendered(
+                    locator, timeout=timeout, max_bytes=max_bytes, deadline=deadline,
+                )
+    except Exception as error:
+        # Playwright has its own TimeoutError; do not retain its locator/URL or
+        # arbitrary upstream exception messages in the public diagnostic.
+        if isinstance(error, TimeoutError) or type(error).__name__ == "TimeoutError":
+            raise TimeoutError("Image capture timed out") from None
+        if isinstance(error, FetchError):
+            raise
+        raise FetchError("Image capture failed", phase="image_capture") from None
+    if not isinstance(png, bytes):
+        raise FetchError("Browser returned invalid image bytes", phase="image_capture")
+    if len(png) > max_bytes:
+        raise ResponseTooLarge("Captured image exceeds max_bytes", phase="image_capture")
+    return CapturedImage(png)
+
+
+async def _capture_rendered(
+    locator: Any, *, timeout: float, max_bytes: int, deadline: float,
+) -> bytes:
+    await _require_visible_area(locator)
+    page = getattr(locator, "page", None)
+    context = getattr(page, "context", None)
+    if page is not None and context is not None and hasattr(context, "new_cdp_session"):
+        try:
+            return await _capture_rendered_cdp(
+                locator,
+                page,
+                context,
+                timeout=timeout,
+                max_bytes=max_bytes,
+            )
+        except FetchError:
+            raise
+        except Exception as error:
+            # CDP is Chromium-only. Other engines and partial adapters retain
+            # the browser-neutral Locator screenshot path.
+            if isinstance(error, TimeoutError) or asyncio.get_running_loop().time() >= deadline:
+                raise
+    return await locator.screenshot(type="png", animations="disabled", timeout=timeout)
+
+
+async def _require_visible_area(locator: Any) -> None:
+    state = await locator.evaluate(
+        """element => {
+          const rect = element.getBoundingClientRect();
+          const style = getComputedStyle(element);
+          return {
+            connected: element.isConnected,
+            width: rect.width,
+            height: rect.height,
+            display: style.display,
+            visibility: style.visibility
+          };
+        }"""
+    )
+    if not isinstance(state, dict):
+        raise FetchError("Browser returned invalid image bounds", phase="image_capture")
+    try:
+        width = float(state["width"])
+        height = float(state["height"])
+    except (KeyError, TypeError, ValueError, OverflowError):
+        raise FetchError("Browser returned invalid image bounds", phase="image_capture") from None
+    if (
+        state.get("connected") is not True
+        or state.get("display") == "none"
+        or state.get("visibility") in {"hidden", "collapse"}
+        or not math.isfinite(width)
+        or not math.isfinite(height)
+        or width <= 0
+        or height <= 0
+    ):
+        raise FetchError("Rendered image has no visible area", phase="image_capture")
+
+
+async def _capture_rendered_cdp(
+    locator: Any,
+    page: Any,
+    context: Any,
+    *,
+    timeout: float,
+    max_bytes: int,
+) -> bytes:
+    await locator.scroll_into_view_if_needed(timeout=timeout)
+    box = await locator.bounding_box(timeout=timeout)
+    if not isinstance(box, dict):
+        raise FetchError("Rendered image is not visible", phase="image_capture")
+    try:
+        x = float(box["x"])
+        y = float(box["y"])
+        width = float(box["width"])
+        height = float(box["height"])
+    except (KeyError, TypeError, ValueError, OverflowError):
+        raise FetchError("Browser returned invalid image bounds", phase="image_capture") from None
+    if (
+        not all(math.isfinite(value) for value in (x, y, width, height))
+        or width <= 0
+        or height <= 0
+    ):
+        raise FetchError("Rendered image has no visible area", phase="image_capture")
+
+    offset = await page.evaluate("() => ({x: window.scrollX, y: window.scrollY})")
+    if not isinstance(offset, dict):
+        raise FetchError("Browser returned invalid page position", phase="image_capture")
+    try:
+        page_x = float(offset["x"])
+        page_y = float(offset["y"])
+    except (KeyError, TypeError, ValueError, OverflowError):
+        raise FetchError("Browser returned invalid page position", phase="image_capture") from None
+    if not math.isfinite(page_x) or not math.isfinite(page_y):
+        raise FetchError("Browser returned invalid page position", phase="image_capture")
+
+    session = await context.new_cdp_session(page)
+    try:
+        result = await session.send(
+            "Page.captureScreenshot",
+            {
+                "format": "png",
+                "captureBeyondViewport": True,
+                "fromSurface": True,
+                "clip": {
+                    "x": x + page_x,
+                    "y": y + page_y,
+                    "width": width,
+                    "height": height,
+                    "scale": 1,
+                },
+            },
+        )
+    finally:
+        await _detach_session(session)
+    if not isinstance(result, dict) or not isinstance(result.get("data"), str):
+        raise FetchError("Browser returned invalid image bytes", phase="image_capture")
+    return _decode_base64(result["data"], max_bytes=max_bytes)
+
+
+async def _capture_loaded_image(locator: Any, *, max_bytes: int) -> bytes:
+    encoded = await locator.evaluate(
+        """image => {
+          if (!(image instanceof HTMLImageElement)) throw new Error('not an image');
+          if (!image.complete || !image.naturalWidth || !image.naturalHeight) {
+            throw new Error('image not loaded');
+          }
+          const canvas = document.createElement('canvas');
+          canvas.width = image.naturalWidth;
+          canvas.height = image.naturalHeight;
+          const context = canvas.getContext('2d');
+          if (!context) throw new Error('canvas unavailable');
+          context.drawImage(image, 0, 0);
+          return canvas.toDataURL('image/png').split(',', 2)[1];
+        }"""
+    )
+    if not isinstance(encoded, str):
+        raise FetchError("Browser returned invalid image bytes", phase="image_capture")
+    return _decode_base64(encoded, max_bytes=max_bytes)
+
+
+async def _detach_session(session: Any) -> None:
+    try:
+        async with asyncio.timeout(0.25):
+            await session.detach()
+    except TimeoutError:
+        pass
+    except Exception:
+        pass
+
+
+def _decode_base64(encoded: str, *, max_bytes: int) -> bytes:
+    max_encoded = 4 * ((max_bytes + 2) // 3)
+    if len(encoded) > max_encoded:
+        raise ResponseTooLarge("Captured image exceeds max_bytes", phase="image_capture")
+    try:
+        return base64.b64decode(encoded, validate=True)
+    except (binascii.Error, ValueError):
+        raise FetchError("Browser returned invalid image bytes", phase="image_capture") from None