zhenxun_bot/zhenxun/services/renderer/engine.py

import asyncio
from collections import OrderedDict
from collections.abc import AsyncIterator, Awaitable, Callable, Coroutine
import contextlib
from dataclasses import dataclass, field
import hashlib
import inspect
import json
from pathlib import Path
import time
from typing import Any, ClassVar, cast

import nonebot_plugin_htmlrender as htmlrender_module
import nonebot_plugin_htmlrender.browser as htmlrender_browser
import psutil

from zhenxun.configs.config import Config
from zhenxun.services.log import logger

from .types import BaseScreenshotEngine

_PLAYWRIGHT_DISCONNECT_ERROR = "Connection closed while reading from the driver"
_PLAYWRIGHT_TARGET_CLOSED_ERROR_MARKERS = (
    "TargetClosedError",
    "Target page, context or browser has been closed",
    "browser has been closed",
    "BrowserContext.new_page",
)
_UNRETRIEVED_FUTURE_MESSAGE = "Future exception was never retrieved"
_LOOP_EXCEPTION_FILTER_STATE_ATTR = "_zhenxun_playwright_exception_filter_state"
_DISCONNECT_SUPPRESSION_WINDOW_SECONDS = 10.0


class HtmlrenderTaskTracker:
    """只追踪 htmlrender 渲染任务的轻量运行时。"""

    def __init__(self) -> None:
        self._lock = asyncio.Lock()
        self._idle_event = asyncio.Event()
        self._idle_event.set()
        self._active_tasks = 0
        self._draining = False
        self._drain_reason: str | None = None

    @property
    def active_tasks(self) -> int:
        return self._active_tasks

    @property
    def is_draining(self) -> bool:
        return self._draining

    async def reset(self) -> None:
        async with self._lock:
            self._draining = False
            self._drain_reason = None
            if self._active_tasks == 0:
                self._idle_event.set()

    async def resume(self) -> None:
        async with self._lock:
            self._draining = False
            self._drain_reason = None

    async def mark_draining(self, reason: str) -> None:
        async with self._lock:
            self._draining = True
            self._drain_reason = reason

    async def begin(self, owner: str) -> None:
        async with self._lock:
            if self._draining:
                reason = self._drain_reason or "unknown"
                message = (
                    "htmlrender 正在排空，拒绝新的渲染任务: "
                    f"owner={owner}, reason={reason}"
                )
                raise RuntimeError(message)
            self._active_tasks += 1
            self._idle_event.clear()

    async def end(self) -> None:
        async with self._lock:
            self._active_tasks = max(0, self._active_tasks - 1)
            if self._active_tasks == 0:
                self._idle_event.set()

    async def wait_for_idle(self) -> None:
        await self._idle_event.wait()

    @contextlib.asynccontextmanager
    async def track(self, owner: str):
        await self.begin(owner)
        try:
            yield
        finally:
            await self.end()


_HTMLRENDER_TASK_TRACKER = HtmlrenderTaskTracker()


@dataclass(slots=True)
class ContextGeneration:
    generation_id: int
    context_pool: asyncio.LifoQueue[Any] = field(default_factory=asyncio.LifoQueue)
    all_contexts: set[Any] = field(default_factory=set)
    active_leases: int = 0
    retiring: bool = False

    def snapshot(self) -> dict[str, int | bool]:
        return {
            "generation_id": self.generation_id,
            "pool_size": self.context_pool.qsize(),
            "context_count": len(self.all_contexts),
            "active_leases": self.active_leases,
            "retiring": self.retiring,
        }


async def _await_if_needed(value: Any) -> Any:
    if inspect.isawaitable(value):
        return await cast(Awaitable[Any], value)
    return value


async def _get_browser_instance() -> Any:
    for attr_name in ("get_browser", "get_new_browser"):
        browser_getter = getattr(htmlrender_browser, attr_name, None)
        if callable(browser_getter):
            return await _await_if_needed(browser_getter())
    raise RuntimeError("nonebot_plugin_htmlrender.browser 未提供可用浏览器获取函数。")


def _is_ignorable_playwright_disconnect(ctx: dict[str, Any]) -> bool:
    exc = ctx.get("exception")
    return (
        ctx.get("message") == _UNRETRIEVED_FUTURE_MESSAGE
        and isinstance(exc, Exception)
        and _PLAYWRIGHT_DISCONNECT_ERROR in str(exc)
    )


def _is_playwright_target_closed_error(exc: Exception) -> bool:
    exc_name = type(exc).__name__
    if exc_name == "TargetClosedError":
        return True
    message = str(exc)
    return any(marker in message for marker in _PLAYWRIGHT_TARGET_CLOSED_ERROR_MARKERS)


def _get_loop_exception_filter_state(
    loop: asyncio.AbstractEventLoop,
) -> dict[str, Any] | None:
    state = getattr(loop, _LOOP_EXCEPTION_FILTER_STATE_ATTR, None)
    if isinstance(state, dict):
        return state
    return None


def _ensure_loop_exception_filter(
    loop: asyncio.AbstractEventLoop,
) -> dict[str, Any]:
    state = _get_loop_exception_filter_state(loop)
    if state is not None:
        return state

    state = {
        "original_handler": loop.get_exception_handler(),
        "suppress_until": 0.0,
    }

    def _filter(lp: asyncio.AbstractEventLoop, ctx: dict[str, Any]) -> None:
        if _is_ignorable_playwright_disconnect(ctx):
            suppress_until = float(state.get("suppress_until", 0.0))
            if suppress_until >= time.monotonic():
                return
        original_handler = state.get("original_handler")
        if callable(original_handler):
            original_handler(lp, ctx)
            return
        lp.default_exception_handler(ctx)

    loop.set_exception_handler(_filter)
    setattr(loop, _LOOP_EXCEPTION_FILTER_STATE_ATTR, state)
    return state


def _arm_disconnect_exception_suppression(
    loop: asyncio.AbstractEventLoop,
    *,
    seconds: float = _DISCONNECT_SUPPRESSION_WINDOW_SECONDS,
) -> None:
    state = _ensure_loop_exception_filter(loop)
    deadline = time.monotonic() + max(seconds, 0.0)
    state["suppress_until"] = max(float(state.get("suppress_until", 0.0)), deadline)


async def _shutdown_browser_instance() -> None:
    loop = asyncio.get_running_loop()
    _arm_disconnect_exception_suppression(loop)

    browser_obj = getattr(htmlrender_browser, "_browser", None)
    playwright_obj = getattr(htmlrender_browser, "_playwright", None)
    if browser_obj is not None:
        is_connected_fn = getattr(browser_obj, "is_connected", None)
        if callable(is_connected_fn) and not is_connected_fn():
            with contextlib.suppress(Exception):
                setattr(htmlrender_browser, "_browser", None)
            with contextlib.suppress(Exception):
                setattr(htmlrender_browser, "_playwright", None)
            return

    if browser_obj is None and playwright_obj is None:
        return

    close_func = getattr(browser_obj, "close", None) if browser_obj else None
    if callable(close_func):
        try:
            await _await_if_needed(close_func())
        except Exception as e:
            if _PLAYWRIGHT_DISCONNECT_ERROR not in str(e):
                logger.debug(f"关闭浏览器实例时忽略异常: {e}")

    stop_func = getattr(playwright_obj, "stop", None) if playwright_obj else None
    if callable(stop_func):
        try:
            await _await_if_needed(stop_func())
        except Exception as e:
            if _PLAYWRIGHT_DISCONNECT_ERROR not in str(e):
                logger.debug(f"关闭 Playwright 实例时忽略异常: {e}")

    with contextlib.suppress(Exception):
        setattr(htmlrender_browser, "_browser", None)
    with contextlib.suppress(Exception):
        setattr(htmlrender_browser, "_playwright", None)

    if callable(close_func) or callable(stop_func):
        await asyncio.sleep(0)


def _patch_htmlrender_task_tracking() -> None:
    if getattr(htmlrender_browser, "_zhenxun_task_tracking_patched", False):
        return

    try:
        import nonebot_plugin_htmlrender.data_source as htmlrender_data_source
    except Exception as e:
        logger.warning("导入 htmlrender.data_source 失败，跳过任务追踪补丁。", e=e)
        return

    original_get_new_page = getattr(htmlrender_browser, "get_new_page", None)
    if not callable(original_get_new_page):
        logger.warning("htmlrender 未提供 get_new_page，跳过任务追踪补丁。")
        return
    original_get_new_page = cast(Callable[..., Any], original_get_new_page)

    @contextlib.asynccontextmanager
    async def _tracked_get_new_page(*args: Any, **kwargs: Any) -> AsyncIterator[Any]:
        async with _HTMLRENDER_TASK_TRACKER.track("htmlrender"):
            page_context = cast(Any, original_get_new_page(*args, **kwargs))
            async with page_context as page:
                yield page

    setattr(htmlrender_browser, "get_new_page", _tracked_get_new_page)
    setattr(htmlrender_module, "get_new_page", _tracked_get_new_page)
    setattr(htmlrender_data_source, "get_new_page", _tracked_get_new_page)
    setattr(htmlrender_browser, "_zhenxun_task_tracking_patched", True)


def _patch_htmlrender_shutdown() -> None:
    if getattr(htmlrender_browser, "_zhenxun_shutdown_patched", False):
        return

    async def _patched_shutdown_browser() -> None:
        if _HTMLRENDER_TASK_TRACKER.is_draining:
            await _HTMLRENDER_TASK_TRACKER.wait_for_idle()
        await _shutdown_browser_instance()

    setattr(htmlrender_browser, "shutdown_browser", _patched_shutdown_browser)
    setattr(htmlrender_module, "shutdown_browser", _patched_shutdown_browser)
    setattr(htmlrender_browser, "_zhenxun_shutdown_patched", True)


def _patch_playwright_env_check_once() -> None:
    _patch_htmlrender_task_tracking()
    _patch_htmlrender_shutdown()
    if getattr(htmlrender_browser, "_zhenxun_check_once_patched", False):
        return

    original_check: Callable[..., Awaitable[Any]] | None = None
    check_attr_name = ""
    for attr_name in ("check_playwright_env", "check_browser_env"):
        candidate = getattr(htmlrender_browser, attr_name, None)
        if callable(candidate):
            original_check = cast(Callable[..., Awaitable[Any]], candidate)
            check_attr_name = attr_name
            break

    if original_check is None:
        logger.debug(
            "未找到 htmlrender 环境检查函数，跳过 check_once 补丁。",
            "PlaywrightEngine",
        )
        setattr(htmlrender_browser, "_zhenxun_check_once_patched", True)
        return

    check_func = original_check
    state: dict[str, Any] = {"checked": False, "result": None}
    check_lock: asyncio.Lock | None = None

    def _is_browser_usable(browser_obj: Any) -> bool:
        if browser_obj is None:
            return False
        is_connected = getattr(browser_obj, "is_connected", None)
        if callable(is_connected):
            with contextlib.suppress(Exception):
                return bool(is_connected())
        # 无法判断连接状态时，保守认为可用
        return True

    def _get_current_browser_candidate() -> Any:
        current = state["result"]
        if _is_browser_usable(current):
            return current
        fallback = getattr(htmlrender_browser, "_browser", None)
        if _is_browser_usable(fallback):
            return fallback
        return None

    async def _check_once(**kwargs: Any) -> Any:
        nonlocal check_lock
        if state["checked"]:
            cached_browser = _get_current_browser_candidate()
            if cached_browser is not None:
                return cached_browser
            state["checked"] = False
            state["result"] = None

        if check_lock is None:
            check_lock = asyncio.Lock()
        async with check_lock:
            if state["checked"]:
                cached_browser = _get_current_browser_candidate()
                if cached_browser is not None:
                    return cached_browser
                state["checked"] = False
                state["result"] = None

            result = await check_func(**kwargs)
            state["checked"] = True
            state["result"] = result

            browser = _get_current_browser_candidate()
            if browser is not None:
                return browser
            return result

    setattr(htmlrender_browser, check_attr_name, _check_once)
    setattr(htmlrender_browser, "_zhenxun_check_once_patched", True)


class PlaywrightEngine(BaseScreenshotEngine):
    """使用 nonebot-plugin-htmlrender 实现的截图引擎。"""

    _MAX_CONCURRENT_RENDER = 4
    _CONTEXT_POOL_SIZE = 4
    _PREWARM_CONTEXT_COUNT = 2
    _SET_CONTENT_WAIT_UNTIL = "domcontentloaded"
    _READY_STATE_TIMEOUT_MS = 2_000
    _IMAGE_READY_TIMEOUT_MS = 1_800
    _FONT_READY_TIMEOUT_MS = 1_200
    _FULL_PAGE_VIEWPORT_MAX_HEIGHT = 4_096
    _FULL_PAGE_VIEWPORT_MAX_WIDTH = 4_096
    _CLIP_PADDING_DEFAULT = 0
    _DISABLE_ANIMATIONS_STYLE = """
        *, *::before, *::after {
            animation: none !important;
            transition: none !important;
            caret-color: transparent !important;
            scroll-behavior: auto !important;
        }
    """
    _RECENT_RESULT_TTL_SECONDS = 1.5
    _RECENT_RESULT_MAX_ITEMS = 64
    _RSS_RECYCLE_MIN_THRESHOLD_BYTES = 700 * 1024 * 1024
    _RSS_RECYCLE_MAX_THRESHOLD_BYTES = 1200 * 1024 * 1024
    _RSS_RECYCLE_HEADROOM_BYTES = 224 * 1024 * 1024
    _RECYCLE_COOLDOWN_SECONDS = 300
    _RECYCLE_CHECK_EVERY = 8
    _IDLE_CHECK_INTERVAL_SECONDS = 15
    _IDLE_RECYCLE_SECONDS = 180
    _POOL_UNSAFE_OPTION_KEYS: ClassVar[set[str]] = {
        "color_scheme",
        "extra_http_headers",
        "forced_colors",
        "geolocation",
        "has_touch",
        "http_credentials",
        "ignore_https_errors",
        "is_mobile",
        "java_script_enabled",
        "locale",
        "permissions",
        "proxy",
        "record_har_content",
        "record_har_mode",
        "record_har_omit_content",
        "record_har_path",
        "record_video_dir",
        "record_video_size",
        "reduced_motion",
        "screen",
        "service_workers",
        "storage_state",
        "timezone_id",
        "user_agent",
    }
    _POOL_DEVICE_SCALE_FACTOR = 2

    def __init__(self):
        _patch_playwright_env_check_once()
        self._render_semaphore = asyncio.Semaphore(self._MAX_CONCURRENT_RENDER)
        self._debug_console_log = bool(Config.get_config("UI", "DEBUG_MODE", False))
        self._state_lock = asyncio.Lock()
        self._recycle_lock = asyncio.Lock()
        self._active_renders = 0
        self._render_count = 0
        self._recycle_pending = False
        self._last_recycle_at = 0.0
        self._last_render_finished_at = time.monotonic()
        self._rss_baseline_bytes: int | None = None
        self._recent_results: OrderedDict[str, tuple[float, bytes]] = OrderedDict()
        self._inflight_tasks: dict[str, asyncio.Task[bytes]] = {}
        self._generation_counter = 0
        self._active_generation: ContextGeneration | None = None
        self._retiring_generations: list[ContextGeneration] = []
        self._idle_recycle_task: asyncio.Task[None] | None = None
        self._closing = False
        self._process = psutil.Process()

    @staticmethod
    def _normalize_base_url(path: Path) -> str:
        base_url = path.absolute().as_uri()
        if not base_url.endswith("/"):
            base_url += "/"
        return base_url

    @staticmethod
    def _build_render_key(
        html: str, template_path: str, render_options: dict[str, Any]
    ) -> str:
        options_json = json.dumps(render_options, sort_keys=True, default=str)
        hasher = hashlib.sha256()
        hasher.update(template_path.encode("utf-8"))
        hasher.update(b"\0")
        hasher.update(options_json.encode("utf-8"))
        hasher.update(b"\0")
        hasher.update(html.encode("utf-8", errors="ignore"))
        return hasher.hexdigest()

    def _cleanup_recent_results_nolock(self, now: float) -> None:
        while self._recent_results:
            expire_at, _ = next(iter(self._recent_results.values()))
            if expire_at > now:
                break
            self._recent_results.popitem(last=False)
        while len(self._recent_results) > self._RECENT_RESULT_MAX_ITEMS:
            self._recent_results.popitem(last=False)

    def _get_recent_result_nolock(self, key: str, now: float) -> bytes | None:
        entry = self._recent_results.get(key)
        if not entry:
            return None
        expire_at, result = entry
        if expire_at <= now:
            self._recent_results.pop(key, None)
            return None
        self._recent_results.move_to_end(key)
        return result

    def _get_total_rss(self) -> int | None:
        try:
            total_rss = self._process.memory_info().rss
            for child in self._process.children(recursive=True):
                with contextlib.suppress(Exception):
                    total_rss += child.memory_info().rss
            return total_rss
        except Exception:
            return None

    def _update_rss_baseline_nolock(self, current_rss: int) -> None:
        if self._rss_baseline_bytes is None or current_rss < self._rss_baseline_bytes:
            self._rss_baseline_bytes = current_rss
            return

        threshold = self._rss_baseline_bytes + self._RSS_RECYCLE_HEADROOM_BYTES * 2
        if current_rss >= threshold:
            self._rss_baseline_bytes = int(
                self._rss_baseline_bytes * 0.9 + current_rss * 0.1
            )

    def _get_dynamic_threshold_nolock(self, current_rss: int) -> int:
        self._update_rss_baseline_nolock(current_rss)
        baseline = self._rss_baseline_bytes or current_rss
        dynamic = baseline + self._RSS_RECYCLE_HEADROOM_BYTES
        dynamic = max(dynamic, self._RSS_RECYCLE_MIN_THRESHOLD_BYTES)
        dynamic = min(dynamic, self._RSS_RECYCLE_MAX_THRESHOLD_BYTES)
        return dynamic

    def _mark_recycle_if_needed_nolock(self, now: float) -> None:
        if self._render_count % self._RECYCLE_CHECK_EVERY != 0:
            return
        if now - self._last_recycle_at < self._RECYCLE_COOLDOWN_SECONDS:
            return
        current_rss = self._get_total_rss()
        if current_rss is None:
            return
        threshold = self._get_dynamic_threshold_nolock(current_rss)
        if current_rss >= threshold:
            self._recycle_pending = True

    async def get_runtime_snapshot(self) -> dict[str, Any]:
        async with self._state_lock:
            active_generation = (
                self._active_generation.snapshot()
                if self._active_generation is not None
                else None
            )
            retiring_generations = [
                generation.snapshot() for generation in self._retiring_generations
            ]
            return {
                "closing": self._closing,
                "active_renders": self._active_renders,
                "render_count": self._render_count,
                "recycle_pending": self._recycle_pending,
                "last_recycle_at": self._last_recycle_at,
                "generation_counter": self._generation_counter,
                "active_generation": active_generation,
                "retiring_generations": retiring_generations,
                "retiring_generation_count": len(retiring_generations),
                "inflight_task_count": len(self._inflight_tasks),
                "recent_result_count": len(self._recent_results),
                "htmlrender_active_tasks": _HTMLRENDER_TASK_TRACKER.active_tasks,
                "htmlrender_draining": _HTMLRENDER_TASK_TRACKER.is_draining,
            }

    async def _log_runtime_snapshot(self, reason: str) -> None:
        snapshot = await self.get_runtime_snapshot()
        logger.trace(
            f"截图引擎状态快照[{reason}]: {snapshot}",
        )

    def _create_generation_nolock(self) -> ContextGeneration:
        self._generation_counter += 1
        return ContextGeneration(generation_id=self._generation_counter)

    def _ensure_active_generation_nolock(self) -> ContextGeneration:
        if self._active_generation is None:
            self._active_generation = self._create_generation_nolock()
        return self._active_generation

    async def initialize(self) -> None:
        async with self._state_lock:
            if self._idle_recycle_task and not self._idle_recycle_task.done():
                return
            self._closing = False
            self._generation_counter = 0
            self._active_generation = None
            self._retiring_generations.clear()
            self._last_render_finished_at = time.monotonic()
            if current_rss := self._get_total_rss():
                self._rss_baseline_bytes = current_rss
            self._idle_recycle_task = asyncio.create_task(self._idle_recycle_loop())
        await _HTMLRENDER_TASK_TRACKER.reset()
        await self._log_runtime_snapshot("initialize")
        # 浏览器在首次 _acquire_context 时按需启动，无需预热

    async def close(self) -> None:
        idle_task: asyncio.Task[None] | None = None
        async with self._state_lock:
            self._closing = True
            idle_task = self._idle_recycle_task
            self._idle_recycle_task = None
            self._recent_results.clear()
            self._recycle_pending = False

        await _HTMLRENDER_TASK_TRACKER.mark_draining("engine_close")

        if idle_task:
            idle_task.cancel()
            with contextlib.suppress(asyncio.CancelledError):
                await idle_task

        await _HTMLRENDER_TASK_TRACKER.wait_for_idle()

        async with self._state_lock:
            inflight_tasks = list(self._inflight_tasks.values())

        if inflight_tasks:
            await asyncio.gather(*inflight_tasks, return_exceptions=True)

        async with self._state_lock:
            self._inflight_tasks.clear()

        await self._log_runtime_snapshot("close:before_dispose")
        await self._dispose_context_pool()
        await _shutdown_browser_instance()
        await self._log_runtime_snapshot("close:after_shutdown")

    async def _on_render_begin(self) -> None:
        await _HTMLRENDER_TASK_TRACKER.begin("zhenxun_renderer")
        async with self._state_lock:
            self._active_renders += 1

    async def _on_render_end(self) -> None:
        should_recycle = False
        async with self._state_lock:
            self._active_renders = max(0, self._active_renders - 1)
            self._render_count += 1
            now = time.monotonic()
            self._last_render_finished_at = now
            self._mark_recycle_if_needed_nolock(now)
            if self._recycle_pending and _HTMLRENDER_TASK_TRACKER.active_tasks == 0:
                self._recycle_pending = False
                self._last_recycle_at = now
                should_recycle = True
        await _HTMLRENDER_TASK_TRACKER.end()
        if should_recycle:
            await self._recycle_browser("active")

    @staticmethod
    def _build_page_options(
        render_options: dict[str, Any], *, pooled: bool
    ) -> dict[str, Any]:
        options = render_options.copy()
        options.pop("wait", None)
        options.pop("type", None)
        options.pop("quality", None)
        options.pop("scale", None)
        options.pop("screenshot_scale", None)
        options.pop("screenshot_timeout", None)
        options.pop("full_page", None)
        options.pop("clip_selector", None)
        options.pop("clip_padding", None)
        options.pop("disable_animations", None)
        if pooled:
            options.pop("base_url", None)
            options.pop("device_scale_factor", None)
        return options

    @staticmethod
    def _build_screenshot_options(render_options: dict[str, Any]) -> dict[str, Any]:
        scale = render_options.get("screenshot_scale", render_options.get("scale"))
        if scale not in ("css", "device"):
            scale = None
        return {
            "full_page": bool(render_options.get("full_page", True)),
            "type": render_options.get("type", "png"),
            "quality": render_options.get("quality"),
            "scale": scale,
            "timeout": render_options.get("screenshot_timeout", 30_000),
        }

    @staticmethod
    def _get_wait_timeout(render_options: dict[str, Any]) -> int:
        wait = render_options.get("wait", 0)
        if isinstance(wait, int):
            return max(wait, 0)
        return 0

    @staticmethod
    def _coerce_non_negative_int(value: Any, default: int = 0) -> int:
        try:
            value_int = int(value)
        except (TypeError, ValueError):
            return default
        return value_int if value_int >= 0 else default

    @classmethod
    def _should_use_context_pool(cls, render_options: dict[str, Any]) -> bool:
        for key in cls._POOL_UNSAFE_OPTION_KEYS:
            if key in render_options:
                return False
        dsf = render_options.get("device_scale_factor")
        if dsf is not None and dsf != cls._POOL_DEVICE_SCALE_FACTOR:
            return False
        return True

    async def _render_with_page(
        self,
        page: Any,
        html: str,
        template_path: str,
        render_options: dict[str, Any],
    ) -> bytes:
        if self._debug_console_log:
            page.on("console", lambda msg: logger.debug(f"浏览器控制台: {msg.text}"))
        await page.goto(template_path, wait_until="commit")
        await page.set_content(html, wait_until=self._SET_CONTENT_WAIT_UNTIL)
        if bool(render_options.get("disable_animations", False)):
            await self._disable_page_animations(page)
        await self._wait_for_visual_stability(page)
        if wait_ms := self._get_wait_timeout(render_options):
            await page.wait_for_timeout(wait_ms)
        screenshot_options = self._build_screenshot_options(render_options)
        clip_selector = render_options.get("clip_selector")
        if isinstance(clip_selector, str) and clip_selector.strip():
            if image_bytes := await self._capture_by_selector(
                page,
                selector=clip_selector.strip(),
                screenshot_options=screenshot_options,
                clip_padding=self._coerce_non_negative_int(
                    render_options.get("clip_padding"),
                    self._CLIP_PADDING_DEFAULT,
                ),
            ):
                return image_bytes
        await self._optimize_full_page_capture(page, screenshot_options)
        return await page.screenshot(**screenshot_options)

    async def _disable_page_animations(self, page: Any) -> None:
        with contextlib.suppress(Exception):
            await page.add_style_tag(content=self._DISABLE_ANIMATIONS_STYLE)

    async def _capture_by_selector(
        self,
        page: Any,
        selector: str,
        screenshot_options: dict[str, Any],
        clip_padding: int,
    ) -> bytes | None:
        element = await page.query_selector(selector)
        if element is None:
            return None

        element_screenshot_options = {
            "type": screenshot_options.get("type", "png"),
            "quality": screenshot_options.get("quality"),
            "timeout": screenshot_options.get("timeout", 30_000),
        }
        with contextlib.suppress(Exception):
            box = await element.bounding_box()
            if box and clip_padding > 0:
                viewport = page.viewport_size or {}
                width = int(viewport.get("width") or 0)
                if width > 0:
                    target_height = int(box["y"] + box["height"] + clip_padding)
                    current_height = int(viewport.get("height") or 0)
                    if target_height > current_height:
                        await page.set_viewport_size(
                            {"width": width, "height": target_height}
                        )

        if clip_padding <= 0:
            return await element.screenshot(**element_screenshot_options)

        with contextlib.suppress(Exception):
            clip_box = await element.bounding_box()
            if clip_box is None:
                return await element.screenshot(**element_screenshot_options)
            clip = {
                "x": max(clip_box["x"] - clip_padding, 0),
                "y": max(clip_box["y"] - clip_padding, 0),
                "width": clip_box["width"] + clip_padding * 2,
                "height": clip_box["height"] + clip_padding * 2,
            }
            page_options = {
                "type": screenshot_options.get("type", "png"),
                "quality": screenshot_options.get("quality"),
                "timeout": screenshot_options.get("timeout", 30_000),
                "clip": clip,
            }
            return await page.screenshot(**page_options)

        return await element.screenshot(**element_screenshot_options)

    async def _wait_for_visual_stability(self, page: Any) -> None:
        # 先做一次快速预检，判断页面是否有外部图片和自定义字体
        resource_hints: dict[str, bool] | None = None
        with contextlib.suppress(Exception):
            resource_hints = await page.evaluate(
                """
                () => {
                    const imgs = document.images || [];
                    let hasUnloadedImages = false;
                    for (let i = 0; i < imgs.length; i++) {
                        if (!imgs[i].complete) { hasUnloadedImages = true; break; }
                    }
                    const hasCustomFonts = !!(
                        document.fonts && document.fonts.size > 0
                    );
                    return {
                        ready: document.readyState === 'complete',
                        images: hasUnloadedImages,
                        fonts: hasCustomFonts,
                    };
                }
                """
            )

        # 如果预检已知全部就绪，直接返回
        if (
            isinstance(resource_hints, dict)
            and resource_hints.get("ready") is True
            and resource_hints.get("images") is not True
            and resource_hints.get("fonts") is not True
        ):
            return

        # 对需要的等待项并行执行
        waiters: list[Coroutine[Any, Any, None]] = []

        need_ready = not (
            isinstance(resource_hints, dict) and resource_hints.get("ready") is True
        )
        need_images = (
            not isinstance(resource_hints, dict) or resource_hints.get("images") is True
        )
        need_fonts = (
            not isinstance(resource_hints, dict) or resource_hints.get("fonts") is True
        )

        if need_ready:
            waiters.append(self._wait_ready_state(page))
        if need_images:
            waiters.append(self._wait_images_loaded(page))
        if need_fonts:
            waiters.append(self._wait_fonts_ready(page))

        if waiters:
            await asyncio.gather(*waiters)

    async def _wait_ready_state(self, page: Any) -> None:
        with contextlib.suppress(Exception):
            await page.wait_for_function(
                "() => document.readyState === 'complete'",
                timeout=self._READY_STATE_TIMEOUT_MS,
            )

    async def _wait_images_loaded(self, page: Any) -> None:
        with contextlib.suppress(Exception):
            await page.wait_for_function(
                "() => Array.from(document.images || []).every(img => img.complete)",
                timeout=self._IMAGE_READY_TIMEOUT_MS,
            )

    async def _wait_fonts_ready(self, page: Any) -> None:
        with contextlib.suppress(Exception):
            await page.evaluate(
                """
                async (timeoutMs) => {
                    if (!document.fonts || !document.fonts.ready) return;
                    await Promise.race([
                        document.fonts.ready,
                        new Promise(resolve => setTimeout(resolve, timeoutMs)),
                    ]);
                }
                """,
                self._FONT_READY_TIMEOUT_MS,
            )

    async def _optimize_full_page_capture(
        self, page: Any, screenshot_options: dict[str, Any]
    ) -> None:
        if not bool(screenshot_options.get("full_page")):
            return

        viewport = page.viewport_size or {}
        width = viewport.get("width")
        height = viewport.get("height")
        if (
            not isinstance(width, int)
            or width <= 0
            or not isinstance(height, int)
            or height <= 0
        ):
            return

        with contextlib.suppress(Exception):
            content_size = await page.evaluate(
                """
                () => {
                    const body = document.body;
                    const doc = document.documentElement;
                    const bodyWidth = body ? Math.max(
                        body.scrollWidth,
                        body.offsetWidth,
                        body.clientWidth
                    ) : 0;
                    const bodyHeight = body ? Math.max(
                        body.scrollHeight,
                        body.offsetHeight,
                        body.clientHeight
                    ) : 0;
                    const docWidth = doc ? Math.max(
                        doc.scrollWidth,
                        doc.offsetWidth,
                        doc.clientWidth
                    ) : 0;
                    const docHeight = doc ? Math.max(
                        doc.scrollHeight,
                        doc.offsetHeight,
                        doc.clientHeight
                    ) : 0;
                    return {
                        width: Math.ceil(Math.max(bodyWidth, docWidth, 10)),
                        height: Math.ceil(Math.max(bodyHeight, docHeight, 10)),
                    };
                }
                """
            )
            if not isinstance(content_size, dict):
                return

            content_width = content_size.get("width")
            content_height = content_size.get("height")
            if not isinstance(content_width, int) or not isinstance(
                content_height, int
            ):
                return
            if content_width < 10 or content_height < 10:
                return

            target_width = min(
                max(width, content_width), self._FULL_PAGE_VIEWPORT_MAX_WIDTH
            )
            target_height = max(height, content_height)
            await page.set_viewport_size(
                {"width": target_width, "height": target_height}
            )
            screenshot_options["full_page"] = False

    async def _render_with_oneoff_page(
        self,
        html: str,
        template_path: str,
        render_options: dict[str, Any],
    ) -> bytes:
        browser = await _get_browser_instance()
        page_options = self._build_page_options(render_options, pooled=False)
        page = await browser.new_page(**page_options)
        try:
            return await self._render_with_page(
                page, html, template_path, render_options
            )
        finally:
            with contextlib.suppress(Exception):
                await page.close()

    async def _dispose_generation(self, generation: ContextGeneration) -> None:
        contexts = list(generation.all_contexts)
        generation.all_contexts.clear()
        while True:
            try:
                generation.context_pool.get_nowait()
            except asyncio.QueueEmpty:
                break

        for context in contexts:
            with contextlib.suppress(Exception):
                await context.close()

    async def _cleanup_retiring_generations(self) -> None:
        disposable: list[ContextGeneration] = []
        async with self._state_lock:
            remaining: list[ContextGeneration] = []
            for generation in self._retiring_generations:
                if generation.active_leases <= 0:
                    disposable.append(generation)
                else:
                    remaining.append(generation)
            self._retiring_generations = remaining

        for generation in disposable:
            await self._dispose_generation(generation)

    async def _dispose_context_pool(self) -> None:
        async with self._state_lock:
            generations: list[ContextGeneration] = []
            if self._active_generation is not None:
                generations.append(self._active_generation)
                self._active_generation = None
            generations.extend(self._retiring_generations)
            self._retiring_generations = []

        for generation in generations:
            await self._dispose_generation(generation)

    async def _build_generation(self) -> ContextGeneration:
        async with self._state_lock:
            generation = self._create_generation_nolock()

        if self._closing:
            return generation

        try:
            browser = await _get_browser_instance()
        except Exception as e:
            logger.warning("截图引擎浏览器预热失败。", "PlaywrightEngine", e=e)
            return generation

        for _ in range(self._PREWARM_CONTEXT_COUNT):
            if self._closing:
                break
            if len(generation.all_contexts) >= self._CONTEXT_POOL_SIZE:
                break

            context = None
            try:
                context = await browser.new_context(
                    viewport={"width": 800, "height": 10},
                    device_scale_factor=2,
                )
                page = await context.new_page()
                await page.goto("about:blank", wait_until="domcontentloaded")
                await page.set_content(
                    "<html><body></body></html>",
                    wait_until="domcontentloaded",
                )
                await page.close()
            except Exception as e:
                logger.warning("截图引擎上下文预热失败。", "PlaywrightEngine", e=e)
                if context is not None:
                    with contextlib.suppress(Exception):
                        await context.close()
                break

            generation.all_contexts.add(context)
            generation.context_pool.put_nowait(context)

        return generation

    async def _swap_generation(self, reason: str) -> None:
        new_generation = await self._build_generation()
        async with self._state_lock:
            old_generation = self._active_generation
            if old_generation is not None:
                old_generation.retiring = True
                self._retiring_generations.append(old_generation)
            self._active_generation = new_generation

        await self._cleanup_retiring_generations()
        logger.debug(
            f"截图引擎触发代际切换({reason})，新代={new_generation.generation_id}",
            "PlaywrightEngine",
        )
        await self._log_runtime_snapshot(f"swap_generation:{reason}")

    async def _acquire_context(self) -> tuple[ContextGeneration, Any]:
        generation: ContextGeneration | None = None
        create_new = False
        async with self._state_lock:
            generation = self._ensure_active_generation_nolock()
            try:
                context = generation.context_pool.get_nowait()
                generation.active_leases += 1
                return generation, context
            except asyncio.QueueEmpty:
                create_new = len(generation.all_contexts) < self._CONTEXT_POOL_SIZE

        if create_new:
            browser = await _get_browser_instance()
            context = await browser.new_context(
                viewport={"width": 800, "height": 10},
                device_scale_factor=2,
            )
            async with self._state_lock:
                target_generation = generation
                if target_generation.retiring and self._active_generation is not None:
                    target_generation = self._active_generation
                target_generation.all_contexts.add(context)
                target_generation.active_leases += 1
                return target_generation, context

        context = await generation.context_pool.get()
        async with self._state_lock:
            generation.active_leases += 1
        return generation, context

    async def _release_context(
        self,
        generation: ContextGeneration,
        context: Any,
        broken: bool = False,
    ) -> None:
        should_discard = broken
        async with self._state_lock:
            generation.active_leases = max(0, generation.active_leases - 1)
            if self._closing or generation.retiring:
                should_discard = True
            elif context not in generation.all_contexts:
                should_discard = True
            elif not should_discard:
                generation.context_pool.put_nowait(context)

        if should_discard:
            await self._discard_context(generation, context)

        await self._cleanup_retiring_generations()

    async def _discard_context(
        self, generation: ContextGeneration, context: Any
    ) -> None:
        async with self._state_lock:
            existed = context in generation.all_contexts
            if existed:
                generation.all_contexts.remove(context)
        if existed:
            with contextlib.suppress(Exception):
                await context.close()

    async def _render_with_context_pool(
        self,
        html: str,
        template_path: str,
        render_options: dict[str, Any],
    ) -> bytes:
        last_error: Exception | None = None
        for attempt in range(2):
            generation, context = await self._acquire_context()
            page = None
            broken = False
            try:
                page = await context.new_page()
                page_options = self._build_page_options(render_options, pooled=True)
                viewport = page_options.get("viewport")
                if isinstance(viewport, dict):
                    width = viewport.get("width")
                    height = viewport.get("height")
                    if isinstance(width, int) and isinstance(height, int):
                        await page.set_viewport_size({"width": width, "height": height})
                return await self._render_with_page(
                    page, html, template_path, render_options
                )
            except Exception as e:
                broken = True
                last_error = e
                if attempt == 0:
                    if _is_playwright_target_closed_error(e):
                        logger.warning(
                            "截图引擎浏览器上下文代已失效，切换新代后重试一次。",
                            "PlaywrightEngine",
                            e=e,
                        )
                        try:
                            await self._swap_generation("target_closed")
                        except Exception:
                            raise e
                    else:
                        logger.warning(
                            "截图引擎上下文已失效，丢弃后重试一次。",
                            "PlaywrightEngine",
                            e=e,
                        )
                    continue
                raise
            finally:
                if page is not None:
                    with contextlib.suppress(Exception):
                        await page.close()
                await self._release_context(generation, context, broken=broken)

        if last_error is not None:
            raise last_error
        raise RuntimeError("截图引擎上下文池渲染失败。")

    async def _render_html(
        self,
        html: str,
        template_path: str,
        render_options: dict[str, Any],
    ) -> bytes:
        if self._should_use_context_pool(render_options):
            return await self._render_with_context_pool(
                html, template_path, render_options
            )
        return await self._render_with_oneoff_page(html, template_path, render_options)

    async def _recycle_browser(self, reason: str) -> None:
        async with self._recycle_lock:
            try:
                await self._swap_generation(reason)
                current_rss = self._get_total_rss()
                if current_rss is not None:
                    self._update_rss_baseline_nolock(current_rss)
                await self._log_runtime_snapshot(f"recycle:{reason}")
            except Exception as e:
                logger.warning("浏览器实例重建失败。", "PlaywrightEngine", e=e)

    async def _prewarm_browser_and_pool(self) -> None:
        if self._closing:
            return
        async with self._state_lock:
            has_active_generation = self._active_generation is not None
        if has_active_generation:
            return

        generation = await self._build_generation()
        dispose_generation = False
        async with self._state_lock:
            if self._closing:
                dispose_generation = True
            elif self._active_generation is None:
                self._active_generation = generation
                return
            else:
                dispose_generation = True

        if dispose_generation:
            await self._dispose_generation(generation)

    async def _idle_recycle_loop(self) -> None:
        while True:
            await asyncio.sleep(self._IDLE_CHECK_INTERVAL_SECONDS)
            should_recycle = False
            async with self._state_lock:
                if self._closing:
                    return
                now = time.monotonic()
                if _HTMLRENDER_TASK_TRACKER.active_tasks > 0:
                    continue
                if now - self._last_recycle_at < self._RECYCLE_COOLDOWN_SECONDS:
                    continue
                idle_for = now - self._last_render_finished_at
                if idle_for < self._IDLE_RECYCLE_SECONDS:
                    continue
                current_rss = self._get_total_rss()
                if current_rss is None:
                    continue
                threshold = self._get_dynamic_threshold_nolock(current_rss)
                if current_rss >= threshold:
                    self._last_recycle_at = now
                    should_recycle = True
            if should_recycle:
                await self._recycle_browser("idle")

    async def _render_and_store_result(
        self,
        key: str,
        html: str,
        base_url_for_browser: str,
        render_options: dict[str, Any],
    ) -> bytes:
        async with self._render_semaphore:
            await self._on_render_begin()
            try:
                result = await self._render_html(
                    html,
                    base_url_for_browser,
                    render_options,
                )
            finally:
                await self._on_render_end()

        async with self._state_lock:
            now = time.monotonic()
            self._recent_results[key] = (
                now + self._RECENT_RESULT_TTL_SECONDS,
                result,
            )
            self._recent_results.move_to_end(key)
            self._cleanup_recent_results_nolock(now)
        return result

    async def render(self, html: str, base_url_path: Path, **render_options) -> bytes:
        if self._closing or _HTMLRENDER_TASK_TRACKER.is_draining:
            raise RuntimeError("截图引擎正在排空/关闭，暂不接受新的渲染任务。")

        base_url_for_browser = self._normalize_base_url(base_url_path)

        final_render_options = {
            "viewport": {"width": 800, "height": 10},
            **render_options,
            "base_url": base_url_for_browser,
        }

        dedupe_key = self._build_render_key(
            html,
            base_url_for_browser,
            final_render_options,
        )

        owner = False
        async with self._state_lock:
            now = time.monotonic()
            self._cleanup_recent_results_nolock(now)
            if cached_result := self._get_recent_result_nolock(dedupe_key, now):
                return cached_result

            task = self._inflight_tasks.get(dedupe_key)
            if task is None:
                task = asyncio.create_task(
                    self._render_and_store_result(
                        dedupe_key,
                        html,
                        base_url_for_browser,
                        final_render_options,
                    )
                )
                self._inflight_tasks[dedupe_key] = task
                owner = True

        try:
            return await task
        finally:
            if owner:
                async with self._state_lock:
                    if self._inflight_tasks.get(dedupe_key) is task:
                        self._inflight_tasks.pop(dedupe_key, None)


class EngineManager:
    """
    引擎管理器，负责加载和提供具体的截图引擎实例。
    未来可在此处根据 Config 读取不同的驱动配置。
    """

    def __init__(self):
        self._engine_class: type[BaseScreenshotEngine] = PlaywrightEngine
        self._instance: BaseScreenshotEngine | None = None

    async def get_engine(self) -> BaseScreenshotEngine:
        if not self._instance:
            self._instance = self._engine_class()
            await self._instance.initialize()
        return self._instance

    async def get_runtime_snapshot(self) -> dict[str, Any]:
        engine = await self.get_engine()
        if isinstance(engine, PlaywrightEngine):
            return await engine.get_runtime_snapshot()
        return {"engine": type(engine).__name__}

    async def close(self):
        if self._instance:
            await self._instance.close()
            self._instance = None


engine_manager = EngineManager()