s-librarykit 0.1.22__tar.gz → 0.2.0__tar.gz

{s_librarykit-0.1.22 → s_librarykit-0.2.0}/CHANGELOG.md

@@ -5,6 +5,19 @@
 [SemVer](https://semver.org/lang/ru/). Релизы помечаются git-тегами `vX.Y.Z`;
 push тега запускает автопубликацию на PyPI (GitLab CI, OIDC Trusted Publishing).
 
+## [0.1.23] — 2026-07-08
+
+### Added
+
+- **`contract.QuotaInfo.limit_source`** (`str | None`, default `None`) — honesty-флаг
+  ИСТОЧНИКА потолка/процента окна лимита (хвост E-GW32 %-модели): ``"fact"`` (реальное
+  окно — probe/заголовки провайдера, provider ``percentage``), ``"spec"`` (generic
+  `LimitSpec.limit`), ``"estimate"`` (оценочный per-tier fallback `TIER_ESTIMATE`),
+  ``None`` = неизвестен (back-compat: старые данные без пометки). Даёт UI отличить
+  реальную квоту (яркий бар) от прикидки («≈X% (оценка)», приглушённо). Проставляется
+  потребителем (`accountpoolkit.LimitAuditor.snapshot`) по приоритету fact → spec →
+  estimate; сам DTO неизменяемый (frozen dataclass), поле опционально.
+
 ## [0.1.22] — 2026-07-07
 
 ### Added

{s_librarykit-0.1.22 → s_librarykit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s-librarykit
-Version: 0.1.22
+Version: 0.2.0
 Summary: Жирный КОРЕНЬ китов: единая error-иерархия, config/retry/paths-утили, checkpoint/resume, транспорт/auth/sessions — общий код для clikit, adapterkit и доменных пакетов.
 Author: Dmitry
 License: MIT

{s_librarykit-0.1.22 → s_librarykit-0.2.0}/librarykit/__init__.py

@@ -1,4 +1,4 @@
-"""librarykit — жирный КОРЕНЬ китов (граф librarykit <- adapterkit <- clikit).
+"""librarykit — жирный КОРЕНЬ китов (fan-in граф: adapterkit → librarykit ← clikit).
 
 Общий код вместо дублирования в clikit/adapterkit и доменных пакетах-потребителях:
 единая error-иерархия (ERROR-HUB), config/paths-утили, политики повторов,
@@ -40,15 +40,6 @@ from librarykit.bulk import (
     run_bulk_async,
 )
 from librarykit.checkpoint import Checkpoint, JsonlSink, RunMetrics
-from librarykit.redaction import (
-    BODY_FIELD_PATTERNS,
-    HEADER_BLACKLIST,
-    SECRET_MASK,
-    excerpt_response_body,
-    sanitize_body,
-    sanitize_headers,
-    truncate_body,
-)
 from librarykit.config_util import (
     AppPaths,
     atomic_write_text,
@@ -62,9 +53,12 @@ from librarykit.config_util import (
 from librarykit.contract import (
     Auth,
     AuthMode,
+    BrowserBackend,
+    BrowserSession,
     Codec,
     Creds,
     ErrorMapper,
+    HttpRequestExecutor,
     LimitSpec,
     PaginationMode,
     Paginator,
@@ -73,10 +67,14 @@ from librarykit.contract import (
     QuotaScope,
     Refreshable,
     RequestBody,
+    RequestExecutionMode,
     ResponseLike,
     SessionRef,
     SessionStoreProtocol,
     StreamTransport,
+    SyncBrowserBackend,
+    SyncBrowserSession,
+    SyncHttpRequestExecutor,
     SyncProactiveRefreshable,
     SyncRefreshable,
     SyncTransport,
@@ -115,6 +113,21 @@ from librarykit.errors import (
     TransportError,
     ValidationError,
 )
+from librarykit.factory import (
+    AutomationDriver,
+    BrowserEngine,
+    BrowserOptions,
+    BrowserProvider,
+    BrowserSessionSettings,
+    create_browser_session,
+    create_request_executor,
+    make_browser_backend,
+    make_transport,
+    register_browser_backend,
+    register_browser_provider,
+    register_request_provider,
+    register_transport,
+)
 
 # forms (W8): кодек form-urlencoded тел с nested-JSON полями (hidden-API write).
 from librarykit.forms import FormCodec
@@ -154,6 +167,15 @@ from librarykit.protocols import (
     LoginRequirements,
     OnboardingProtocol,
 )
+from librarykit.redaction import (
+    BODY_FIELD_PATTERNS,
+    HEADER_BLACKLIST,
+    SECRET_MASK,
+    excerpt_response_body,
+    sanitize_body,
+    sanitize_headers,
+    truncate_body,
+)
 from librarykit.refresh import (
     DEFAULT_ROTATE_INTERVAL,
     Keepalive,
@@ -201,6 +223,8 @@ from librarykit.stream import (
 # выведен наверх (нужен потребителям form-urlencoded write / chunked-аплоада).
 from librarykit.transport import (
     HttpClient,
+    HttpxRequestExecutor,
+    HttpxSyncRequestExecutor,
     HttpxSyncTransport,
     HttpxTransport,
     RestHttpClient,
@@ -220,7 +244,7 @@ from librarykit.windows import (
     parse_window,
 )
 
-__version__ = "0.1.22"
+__version__ = "0.2.0"
 
 __all__ = [
     "__version__",
@@ -263,15 +287,36 @@ __all__ = [
     "PaginationMode",
     "AuthMode",
     "TransportKind",
+    "RequestExecutionMode",
     "SessionRef",
     "Creds",
     "RequestBody",
     "ResponseLike",
     "Transport",
     "SyncTransport",
+    "HttpRequestExecutor",
+    "SyncHttpRequestExecutor",
     "StreamTransport",
+    "BrowserBackend",
+    "SyncBrowserBackend",
+    "BrowserSession",
+    "SyncBrowserSession",
     "Codec",
     "Auth",
+    # factory — нейтральный выбор транспорта/браузера по роли (Enum → фабрика → реестр)
+    "BrowserEngine",
+    "BrowserProvider",
+    "AutomationDriver",
+    "BrowserOptions",
+    "BrowserSessionSettings",
+    "make_transport",
+    "register_transport",
+    "create_request_executor",
+    "register_request_provider",
+    "make_browser_backend",
+    "register_browser_backend",
+    "create_browser_session",
+    "register_browser_provider",
     "Refreshable",
     "ProactiveRefreshable",
     "SyncRefreshable",
@@ -305,10 +350,12 @@ __all__ = [
     "resolve_kek",
     # transport (W4): конкретный httpx-транспорт + choke-point клиент
     "HttpxTransport",
+    "HttpxRequestExecutor",
     "HttpClient",
     "RestHttpClient",
     # transport sync-сиблинги (для навыков без event-loop)
     "HttpxSyncTransport",
+    "HttpxSyncRequestExecutor",
     "SyncHttpClient",
     # forms (W8): кодек form-urlencoded тел с nested-JSON полями
     "FormCodec",

s_librarykit-0.2.0/librarykit/antibot/__init__.py

@@ -0,0 +1,126 @@
+"""Антибот-стратегия (КОРЕНЬ китов, W4) как ВЫБОР ТРАНСПОРТА, а не переписывание.
+
+Перенесено из `adapterkit.antibot` в жирный КОРЕНЬ `librarykit` (граф
+`librarykit <- adapterkit <- clikit`); `adapterkit.antibot` — тонкий реэкспорт.
+curl-cffi — ОПЦИОНАЛЬНЫЙ extra `[antibot]` (ленивый импорт внутри транспорта),
+librarykit-without-extras не падает на import пакета.
+
+Идея (spec §2, recipes/antibot reverse-factory): антибот — это не «headless vs
+residential proxy», а пять уровней архитектуры (Tier 0-4). Сервис «опт-инится» в
+нужный уровень, просто выбрав транспорт у эндпоинта (`Endpoint.transport`):
+
+- `TransportKind.HTTP`      → `HttpxTransport`  (Tier 0, обычный httpx) — другой модуль;
+- `TransportKind.CURL_CFFI` → `CurlCffiTransport` (Tier 1-3, JA3-имитация Chrome);
+- `TransportKind.BROWSER`   → `CdpTransport`    (Tier 0-1, реальный системный Edge/Chrome).
+
+Каждый из них реализует ОДИН И ТОТ ЖЕ контракт `librarykit.contract.Transport`
+(`async request(method, url, *, ...) -> httpx.Response`), поэтому вышестоящий код
+(`HttpClient`/`ErrorMapper`/адаптер) не различает транспорты — меняется только
+TLS-fingerprint и источник заголовков, но НЕ форма вызова. Маппинг кодов в
+доменные ошибки — НЕ здесь (это `HttpClient`/`ErrorMapper`); транспорт бросает
+`TransportError` только на сетевых сбоях и возвращает сырой `httpx.Response`.
+
+Этот пакет — ТОНКИЙ ФАСАД: механически разнесён по ответственности на подмодули
+(`._helpers` — обёртка ошибок + нормализация ответа; `.curl_cffi` —
+`CurlCffiTransport`/`pick_chrome_impersonate`; `.cdp` — `CdpTransport`/
+`SyncCdpTransport` + backend-контракты; `.page_evaluate` — `PageEvaluateTransport`/
+`page_fetch`/`_build_fetch_spec`). Публичный API прежний — все прежние имена
+реэкспортированы.
+
+Опциональные зависимости (`curl_cffi`, `playwright`/`patchright`) импортируются
+ЛЕНИВО — модуль импортируется без них (graceful), а понятная ошибка о
+недостающем пакете возникает только при реальной попытке использовать транспорт.
+
+────────────────────────────────────────────────────────────────────────────────
+Tier 0-4 — какой транспорт выбрать под нагрузку и характер защиты
+────────────────────────────────────────────────────────────────────────────────
+Антибот эскалируется уровнями; не «беги за прокси первым», а подбирай по симптому.
+
+- **Tier 0** — видимый браузер (headed) / обычный httpx. RAM ~800 МБ. dev / debug /
+  первый bootstrap-логин. Здесь: `CdpTransport(headless=False)` / `HttpxTransport`.
+- **Tier 1** — headless реальный браузер (CDP→Edge `--headless=new`), ~700 мс,
+  500-800 МБ; prod 1-100 calls/day, антибот средний. Здесь: `CdpTransport(headless=True)`.
+  Вариант того же уровня — curl-cffi (JA3-имитация Chrome), ~10 МБ: JA3/TLS-детект
+  (Akamai, Google) БЕЗ signing. Здесь: `CurlCffiTransport`.
+- **Tier 2** — jsdom one-shot subprocess, 3-5 с, 30-50 МБ; init-флоу известен,
+  sign-only без рендера. Вне этого модуля.
+- **Tier 3** — jsdom persistent daemon (RPC), ~50 мс, ~80 МБ; prod sweet-spot
+  100-10K calls/day. Вне этого модуля.
+- **Tier 4** — pure native (Python/Go/Rust), ~1 мс, ~10 МБ; bundle pinned forever
+  + есть команда сопровождения. Вне этого модуля.
+
+Дерево решений:
+- read-only без подписи запроса → Tier 0/1 (или официальный REST, если есть);
+- мутирующий вызов с подписью (X-Sign/X-Bogus/_signature/msToken):
+  * bootstrap-логин → `CdpTransport` (реальный Edge ставит нативные
+    `sec-fetch-*` / Client-Hints / TLS — patchright их НЕ шлёт);
+  * массовая prod-нагрузка → Tier 3 jsdom-daemon (вне adapterkit), а Python-сторона
+    шлёт уже подписанный URL через `CurlCffiTransport` (JA3 совпадает).
+
+Симптом → направление (три ОРТОГОНАЛЬНЫХ оси, выбирай по симптому, не «по простоте»):
+- `403`/`Access denied` на любом IP, RU-регион заблокирован → IP/proxy (дорого, last resort);
+- видимый captcha-виджет (hCaptcha/Turnstile) → внешний solver (reCAPTCHA v3 — score-based,
+  solver НЕ работает, только реальный браузер `CdpTransport`);
+- `signatures don't match` / `isTTwidDecryptedFail` / «unusual activity» / нет
+  `sec-fetch-*` → архитектура: `CdpTransport` (реальный Edge);
+- `ECONNRESET` / другой контент на JA3-detection endpoint → архитектура: `CurlCffiTransport`.
+
+Железные правила (анти-паттерны):
+- версию Chrome НЕ пинить: захардкоженный `chrome131` через 4+ версии — сигнал «бот»
+  (`CurlCffiTransport` подбирает свежайший доступный профиль автоматически);
+- UA major == sec-ch-ua major == curl-cffi `impersonate` major — рассинхрон палится;
+- `CdpTransport` берёт версию браузера сам — держи системный Edge/Chrome обновлённым.
+"""
+from __future__ import annotations
+
+from ._helpers import (  # noqa: F401  # seam: тесты/потребители импортируют приватные
+    _as_transport_error,
+    _to_httpx_response,
+)
+from .cdp import (
+    CdpBrowserBackend,
+    CdpTransport,
+    SyncCdpBrowserBackend,
+    SyncCdpTransport,
+)
+from .curl_cffi import CurlCffiTransport, pick_chrome_impersonate
+from .page_evaluate import (
+    PageEvaluateTransport,
+    PageFetchResult,
+    _build_fetch_spec,  # noqa: F401  # seam: browser+тесты импортируют
+    page_fetch,
+    sync_page_fetch,
+)
+
+# Первичные ролевые имена исполнителей запроса (роль снаружи, вендор — внутри):
+#   ImpersonatedHttpExecutor  — TLS/JA3-impersonate (curl-cffi) [было CurlCffiTransport];
+#   BrowserRequestExecutor    — запрос «руками браузера» по CDP/CamouFox [было CdpTransport];
+#   BorrowedPageRequestExecutor — запрос в ЗАИМСТВОВАННОЙ странице [было PageEvaluateTransport];
+#   BrowserRequester          — роль «умеет выполнить запрос в браузере» [было CdpBrowserBackend].
+# Старые имена остаются deprecated-псевдонимами (ничего не удалено).
+ImpersonatedHttpExecutor = CurlCffiTransport
+BrowserRequestExecutor = CdpTransport
+SyncBrowserRequestExecutor = SyncCdpTransport
+BorrowedPageRequestExecutor = PageEvaluateTransport
+BrowserRequester = CdpBrowserBackend
+SyncBrowserRequester = SyncCdpBrowserBackend
+
+__all__ = [
+    "CurlCffiTransport",
+    "CdpTransport",
+    "CdpBrowserBackend",
+    "SyncCdpTransport",
+    "SyncCdpBrowserBackend",
+    "PageEvaluateTransport",
+    "PageFetchResult",
+    "page_fetch",
+    "sync_page_fetch",
+    "pick_chrome_impersonate",
+    # первичные ролевые имена (псевдонимы вендор-классов выше)
+    "ImpersonatedHttpExecutor",
+    "BrowserRequestExecutor",
+    "SyncBrowserRequestExecutor",
+    "BorrowedPageRequestExecutor",
+    "BrowserRequester",
+    "SyncBrowserRequester",
+]

s_librarykit-0.2.0/librarykit/antibot/_helpers.py

@@ -0,0 +1,69 @@
+"""Общие хелперы антибот-транспортов: обёртка ошибок + нормализация ответа.
+
+Выделено из god-модуля `antibot.py`. Имена реэкспортируются фасадом
+`librarykit.antibot`; публичный API прежний.
+"""
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from librarykit.errors import TransportError
+
+
+@contextlib.contextmanager
+def _as_transport_error(prefix: str) -> Iterator[None]:
+    """Обернуть сбой backend'а транспорта в `TransportError` с единым префиксом.
+
+    Устраняет повтор ``except Exception → TransportError(f"<prefix>: ...")`` в
+    request-методах транспортов (curl_cffi / CDP / CDP(sync) / page.evaluate).
+    Уже-`TransportError` пробрасывается КАК ЕСТЬ — не заворачиваем дважды (префикс
+    и цепочка причин остаются исходными); прочее исключение backend'а
+    сворачивается в `TransportError` с типом и текстом.
+    """
+    try:
+        yield
+    except TransportError:
+        raise
+    except Exception as exc:
+        raise TransportError(f"{prefix}: {type(exc).__name__}: {exc}") from exc
+
+
+def _to_httpx_response(
+    raw: Any, *, request: httpx.Request, default_encoding: str = "utf-8"
+) -> httpx.Response:
+    """Сконвертировать ответ стороннего backend (curl-cffi) в `httpx.Response`.
+
+    Нормализует разнотипный ответ к единому контракту `Transport`: вышестоящий код
+    (`ErrorMapper`/адаптер) работает только с `httpx.Response`. Тянем status/headers/
+    тело и привязываем реконструированный `httpx.Request` (нужен для url в ошибках).
+    """
+    status = int(getattr(raw, "status_code", 0) or 0)
+    raw_headers = getattr(raw, "headers", None) or {}
+    headers = dict(raw_headers.items()) if hasattr(raw_headers, "items") else dict(raw_headers)
+    # curl-cffi (libcurl) уже РАСПАКОВАЛ тело (Accept-Encoding согласуется при
+    # impersonate), но оставил исходные Content-Encoding/Content-Length. Пробросив
+    # их в httpx.Response с уже-распакованным content, мы заставим httpx
+    # распаковать ПОВТОРНО на .text/.json/.content → `Error -3 while decompressing
+    # data: incorrect header check`. Тело здесь финальное → снимаем эти заголовки.
+    headers = {
+        name: value
+        for name, value in headers.items()
+        if name.lower() not in ("content-encoding", "content-length")
+    }
+    content = getattr(raw, "content", None)
+    if content is None:
+        text = getattr(raw, "text", "") or ""
+        content = text.encode(default_encoding)
+    elif isinstance(content, str):
+        content = content.encode(default_encoding)
+    return httpx.Response(
+        status,
+        headers=headers,
+        content=content,
+        request=request,
+        default_encoding=default_encoding,
+    )

s_librarykit-0.2.0/librarykit/antibot/cdp.py

@@ -0,0 +1,272 @@
+"""CDP-транспорты: подключение к реальному системному Edge/Chrome (antibot Tier 0-1).
+
+Выделено из god-модуля `antibot.py`. Async `CdpTransport` + sync `SyncCdpTransport`
+и их backend-контракты. Имена реэкспортируются фасадом `librarykit.antibot`;
+публичный API прежний.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Literal, Protocol, runtime_checkable
+
+import httpx
+
+from librarykit.contract import SyncTransport, Transport
+from librarykit.errors import TransportError
+
+from ._helpers import _as_transport_error, _to_httpx_response
+
+# =========================================================================== #
+# Tier 0-1: CDP-транспорт (подключение к реальному системному Edge/Chrome)     #
+# =========================================================================== #
+
+
+@runtime_checkable
+class CdpBrowserBackend(Protocol):
+    """Контракт «движка реального браузера» под `CdpTransport` (точка DI).
+
+    Скрывает за собой запуск системного Edge/Chrome с `--remote-debugging-port`
+    и `connect_over_cdp` (см. recipes/antibot `cdp_real_browser.py`). Реализация —
+    в `librarykit.browser` (Playwright/patchright); здесь — только контракт, чтобы
+    `antibot` не тащил тяжёлый browser-стек и тестировался фейком той же формы.
+    """
+
+    async def fetch(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Выполнить запрос внутри реального браузера; вернуть ответоподобный объект.
+
+        Объект нормализуется `_to_httpx_response` (нужны `status_code`/`headers`/
+        `content`|`text`). Браузер сам ставит нативные `sec-fetch-*` / Client-Hints
+        / TLS-fingerprint — ради чего CDP-транспорт и существует.
+        """
+        ...
+
+    async def aclose(self) -> None:
+        """Отключить CDP и завершить процесс браузера (idempotent)."""
+        ...
+
+
+class CdpTransport(Transport):
+    """Транспорт через РЕАЛЬНЫЙ системный Edge/Chrome по CDP (antibot Tier 0-1).
+
+    PRIMARY-путь для signing-heavy сервисов (TikTok / WB seller / Bitrix24-auth):
+    реальный браузер сам ставит нативный триплет `sec-fetch-{dest,mode,site}`,
+    корректные Client-Hints и TLS-fingerprint, которых нет у patchright (симптомы
+    `isTTwidDecryptedFail`, `signatures don't match`, «unusual activity»). `headless`
+    переключает Tier 0 (видимый, debug/bootstrap) ↔ Tier 1 (`--headless=new`, prod
+    1-100 calls/day).
+
+    Сам тяжёлый browser-движок инкапсулирован в `CdpBrowserBackend` (реализация —
+    `librarykit.browser`), который внедряется в конструктор. Так `antibot`:
+    1) не импортирует Playwright/patchright (опциональны → graceful);
+    2) реализует ровно `librarykit.contract.Transport` (взаимозаменяем с остальными);
+    3) детерминированно тестируется фейк-backend без реального браузера.
+
+    Параметры:
+    - `backend`  — реализация `CdpBrowserBackend` (composition root внедряет реальную);
+    - `headless` — Tier 1 (`True`) против Tier 0 (`False`); пробрасывается в реализацию;
+    - `prefer`   — предпочесть ``"edge"`` или ``"chrome"`` (Edge стабильнее на Windows);
+    - `headers`  — базовые заголовки, доливаемые к каждому запросу.
+
+    Если `backend=None` и реальный движок не сконфигурирован — первый `request`
+    бьёт понятным `TransportError` (а не падает при импорте модуля).
+    """
+
+    def __init__(
+        self,
+        *,
+        backend: CdpBrowserBackend | None = None,
+        headless: bool = True,
+        prefer: Literal["chrome", "edge"] = "edge",
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self._backend = backend
+        self.headless = headless
+        self.prefer: Literal["chrome", "edge"] = prefer
+        self._headers: dict[str, str] = dict(headers) if headers else {}
+
+    def _ensure_backend(self) -> CdpBrowserBackend:
+        """Вернуть browser-backend или объяснить, что реальный движок не подключён.
+
+        В spine `antibot` НЕ создаёт Playwright-backend сам (он живёт в
+        `librarykit.browser`); composition root внедряет его через конструктор.
+        """
+        if self._backend is None:
+            raise TransportError(
+                "CdpTransport требует CdpBrowserBackend (реальный Edge/Chrome через CDP). "
+                "Передайте backend=... из librarykit.browser или установите extra 'browser' "
+                "(uv sync --extra browser)."
+            )
+        return self._backend
+
+    async def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        content: bytes | str | None = None,
+        headers: Mapping[str, str] | None = None,
+        files: Any | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Выполнить запрос внутри реального браузера и вернуть `httpx.Response`.
+
+        `files` контрактом принимается, но в браузерном fetch не применяется
+        (multipart внутри страницы — отдельный сценарий); передаётся `None`. Сбой
+        браузера/CDP → `TransportError`. Маппинг статусов — выше по стеку.
+
+        ``content`` (сырое тело) сворачивается в ``data`` (у in-page fetch один слот
+        тела), если ``data`` не задан.
+        """
+        backend = self._ensure_backend()
+        body = data if data is not None else content  # один слот тела у in-page fetch
+        merged_headers = {**self._headers, **(dict(headers) if headers else {})}
+        req = httpx.Request(
+            method,
+            url,
+            params=params,
+            headers=merged_headers or None,
+            cookies=cookies,
+            json=json,
+            data=data,
+            content=content,  # сырое тело через content= (без httpx-deprecation)
+        )
+        with _as_transport_error("CDP"):
+            raw = await backend.fetch(
+                method,
+                url,
+                params=dict(params) if params else None,
+                json=json,
+                data=body,
+                headers=merged_headers or None,
+                cookies=dict(cookies) if cookies else None,
+            )
+        return _to_httpx_response(raw, request=req)
+
+    async def aclose(self) -> None:
+        """Закрыть browser-backend (отключить CDP, завершить процесс), если он есть."""
+        if self._backend is not None:
+            await self._backend.aclose()
+
+    async def __aenter__(self) -> CdpTransport:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+# =========================================================================== #
+# Sync-сиблинги: браузер-backend + транспорт БЕЗ event-loop (для sync-навыков)  #
+# =========================================================================== #
+
+
+@runtime_checkable
+class SyncCdpBrowserBackend(Protocol):
+    """Sync-сиблинг `CdpBrowserBackend`: движок реального/stealth-браузера БЕЗ await.
+
+    Та же роль (выполнить запрос внутри живого браузера, вернуть ответоподобный
+    объект под `_to_httpx_response`), но синхронная сигнатура — для навыков без
+    event-loop. Реализация — `librarykit.browser.SyncCamoufoxBackend`.
+    """
+
+    def fetch(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> Any:
+        """Выполнить запрос внутри браузера; вернуть ответоподобный объект (sync)."""
+        ...
+
+    def close(self) -> None:
+        """Завершить браузер/сессию (idempotent)."""
+        ...
+
+
+class SyncCdpTransport(SyncTransport):
+    """Sync-сиблинг `CdpTransport`: запрос через sync браузер-backend → `httpx.Response`.
+
+    Точная параллель `CdpTransport`, но синхронная: реализует `contract.SyncTransport`
+    (взаимозаменяем с `HttpxSyncTransport` в `SyncHttpClient`). Движок — внедряемый
+    `SyncCdpBrowserBackend` (напр. `SyncCamoufoxBackend`); маппинг кодов в доменные
+    ошибки — выше (`SyncHttpClient`/`ErrorMapper`).
+    """
+
+    def __init__(
+        self,
+        *,
+        backend: SyncCdpBrowserBackend | None = None,
+        headers: Mapping[str, str] | None = None,
+    ) -> None:
+        self._backend = backend
+        self._headers: dict[str, str] = dict(headers) if headers else {}
+
+    def _ensure_backend(self) -> SyncCdpBrowserBackend:
+        if self._backend is None:
+            raise TransportError(
+                "SyncCdpTransport требует SyncCdpBrowserBackend (напр. "
+                "librarykit.browser.SyncCamoufoxBackend)."
+            )
+        return self._backend
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+        data: Any | None = None,
+        content: bytes | str | None = None,
+        headers: Mapping[str, str] | None = None,
+        files: Any | None = None,
+        cookies: Mapping[str, str] | None = None,
+    ) -> httpx.Response:
+        """Выполнить запрос в браузере (sync) и вернуть `httpx.Response`.
+
+        ``content`` сворачивается в ``data`` (у in-page fetch один слот тела), если
+        ``data`` не задан. ``files`` не применяется (multipart внутри страницы —
+        отдельный сценарий). Сбой браузера → `TransportError`.
+        """
+        backend = self._ensure_backend()
+        body = data if data is not None else content  # один слот тела у in-page fetch
+        merged_headers = {**self._headers, **(dict(headers) if headers else {})}
+        req = httpx.Request(
+            method, url, params=params, headers=merged_headers or None,
+            cookies=cookies, json=json, data=data, content=content,
+        )
+        with _as_transport_error("CDP(sync)"):
+            raw = backend.fetch(
+                method, url, params=dict(params) if params else None,
+                json=json, data=body, headers=merged_headers or None,
+                cookies=dict(cookies) if cookies else None,
+            )
+        return _to_httpx_response(raw, request=req)
+
+    def close(self) -> None:
+        """Закрыть browser-backend (sync), если он есть."""
+        if self._backend is not None:
+            self._backend.close()
+
+    def __enter__(self) -> SyncCdpTransport:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()