trcc-linux 5.0.4__tar.gz → 5.0.6__tar.gz

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trcc-linux
-Version: 5.0.4
+Version: 5.0.6
 Summary: Linux implementation of Thermalright LCD Control Center
 Project-URL: Homepage, https://github.com/Lexonight1/thermalright-trcc-linux
 Project-URL: Documentation, https://github.com/Lexonight1/thermalright-trcc-linux#readme

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trcc-linux"
-version = "5.0.4"
+version = "5.0.6"
 description = "Linux implementation of Thermalright LCD Control Center"
 readme = "README.md"
 license = "GPL-3.0-or-later"

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/src/trcc/__version__.py

@@ -1,6 +1,6 @@
 """TRCC Linux version information."""
 
-__version__ = "5.0.4"
+__version__ = "5.0.6"
 __version_info__ = tuple(int(x) for x in __version__.split("."))
 
 # Version history:
@@ -207,3 +207,11 @@ __version_info__ = tuple(int(x) for x in __version__.split("."))
 #          mode flags matching C# FormCZTV.ImageTo565() mode 3. Without the
 #          magic, firmware rejects frames — causing USB disconnect (#16) or
 #          stuck-on-logo (#28). 2353 tests.
+# 5.0.5  - Fix FBL 50 resolution: was (240, 320) portrait, should be
+#          (320, 240) landscape — C# default directionB=0 creates Bitmap(320,240).
+#          Fixes black bars on Mjolnir Vision 360 (#22). Renderer ABC refactor:
+#          Strategy pattern for overlay compositing (PilRenderer adapter).
+#          Overlay caching: text+mask layer cached, re-rendered only on input
+#          change (~1/sec). Fix RGBA transparency bug in overlay layer.
+#          Cloud theme fix: QTimer bound method wrapper, slideshow timer guards.
+#          2395 tests.

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/src/trcc/adapters/infra/theme_cloud.py

@@ -68,6 +68,7 @@ SERVERS = {
 RESOLUTION_URLS = {
     "240x240": "bj240240",
     "240x320": "bj240320",
+    "320x240": "bj320240",
     "320x320": "bj320320",
     "360x360": "bj360360",
     "480x480": "bj480480",

trcc_linux-5.0.6/src/trcc/adapters/render/__init__.py

@@ -0,0 +1 @@
+"""Render adapters — concrete Renderer implementations."""

trcc_linux-5.0.6/src/trcc/adapters/render/pil.py

@@ -0,0 +1,73 @@
+"""PIL/Pillow rendering backend — CPU-only, headless.
+
+Extracts the PIL calls previously inline in OverlayService into the
+Renderer ABC interface.  Behaviour is identical to the original code.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from PIL import Image, ImageDraw
+
+from ...services.renderer import Renderer
+from ..infra.font_resolver import FontResolver
+
+
+class PilRenderer(Renderer):
+    """CPU-only renderer using PIL/Pillow.
+
+    Used by CLI, API, and as default fallback when no Qt is available.
+    """
+
+    def __init__(self) -> None:
+        self._fonts = FontResolver()
+
+    # ── Surface lifecycle ─────────────────────────────────────────
+
+    def create_surface(self, width: int, height: int,
+                       color: tuple[int, ...] | None = None) -> Any:
+        if color:
+            return Image.new('RGB', (width, height), color)
+        return Image.new('RGBA', (width, height), (0, 0, 0, 0))
+
+    def copy_surface(self, surface: Any) -> Any:
+        return surface.copy()
+
+    def convert_to_rgba(self, surface: Any) -> Any:
+        return surface.convert('RGBA') if surface.mode != 'RGBA' else surface
+
+    def convert_to_rgb(self, surface: Any) -> Any:
+        return surface.convert('RGB') if surface.mode != 'RGB' else surface
+
+    # ── Drawing ───────────────────────────────────────────────────
+
+    def composite(self, base: Any, overlay: Any,
+                  position: tuple[int, int],
+                  mask: Any | None = None) -> Any:
+        base.paste(overlay, position, mask or overlay)
+        return base
+
+    def resize(self, surface: Any, width: int, height: int) -> Any:
+        return surface.resize((width, height), Image.Resampling.LANCZOS)
+
+    def draw_text(self, surface: Any, x: int, y: int, text: str,
+                  color: str, font: Any, anchor: str = 'mm') -> None:
+        draw = ImageDraw.Draw(surface)
+        draw.text((x, y), text, fill=color, font=font, anchor=anchor)
+
+    # ── Fonts ─────────────────────────────────────────────────────
+
+    def get_font(self, size: int, bold: bool = False,
+                 font_name: str | None = None) -> Any:
+        return self._fonts.get(size, bold, font_name)
+
+    def clear_font_cache(self) -> None:
+        self._fonts.clear_cache()
+
+    # ── PIL boundary (identity — already PIL) ─────────────────────
+
+    def to_pil(self, surface: Any) -> Any:
+        return surface
+
+    def from_pil(self, image: Any) -> Any:
+        return image

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/src/trcc/core/controllers.py

@@ -529,10 +529,6 @@ class LCDDeviceController:
 
         self._fire_preview(result['preview'])
 
-        if result.get('progress'):
-            # Progress is forwarded by VideoController callbacks
-            pass
-
         send_img = result.get('send_image')
         if send_img:
             self.devices.send_pil_async(
@@ -571,8 +567,9 @@ class LCDDeviceController:
         self._display.current_image = frame
 
     def _on_device_selected(self, device: DeviceInfo):
-        if device.resolution != (self.lcd_width, self.lcd_height):
-            self.set_resolution(*device.resolution)
+        w, h = device.resolution
+        if (w, h) != (0, 0) and (w, h) != (self.lcd_width, self.lcd_height):
+            self.set_resolution(w, h)
         self._fire_status(f"Device: {device.path}")
 
     # ── Private helpers (fire callbacks, send to LCD) ─────────────────

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/src/trcc/core/models.py

@@ -1135,7 +1135,7 @@ LOCALE_TO_LANG: dict[str, str] = {
 FBL_TO_RESOLUTION: dict[int, tuple[int, int]] = {
     36:  (240, 240),
     37:  (240, 240),
-    50:  (240, 320),
+    50:  (320, 240),
     51:  (320, 240),
     54:  (360, 360),
     64:  (640, 480),

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/src/trcc/qt_components/base.py

@@ -203,7 +203,8 @@ class ImageLabel(QLabel):
                 (self._width, self._height), resampling
             )
 
-        self.setPixmap(pil_to_pixmap(pil_image))
+        pixmap = pil_to_pixmap(pil_image)
+        self.setPixmap(pixmap)
 
     def mousePressEvent(self, event):
         """Handle mouse click — start drag."""

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/src/trcc/qt_components/qt_app_mvc.py

@@ -500,7 +500,9 @@ class TRCCMainWindowMVC(QMainWindow):
         self.controller = create_controller(self._data_dir)
 
         # Timers (view owns timers, controller owns logic)
-        self._animation_timer = self._make_timer(self.controller.video_tick)
+        def _video_tick_wrapper():
+            self.controller.video_tick()
+        self._animation_timer = self._make_timer(_video_tick_wrapper)
         self._metrics_timer = self._make_timer(self._on_metrics_tick)
         self._device_timer = self._make_timer(self._on_device_poll)
         self._flash_timer = self._make_timer(self._on_flash_timeout, single_shot=True)
@@ -1482,6 +1484,8 @@ class TRCCMainWindowMVC(QMainWindow):
         Cloud videos are backgrounds — overlay (mask + metrics) persists.
         Don't stop metrics; they keep rendering on top of video frames.
         """
+        # Stop slideshow — cloud video must not be overwritten by carousel
+        self._slideshow_timer.stop()
         # Reset background/screencast modes (cloud theme overrides)
         self._background_active = False
         self._screencast.stop()
@@ -1986,6 +1990,10 @@ class TRCCMainWindowMVC(QMainWindow):
 
     def _on_slideshow_tick(self):
         """Auto-rotate to next theme in slideshow (Windows Timer_event lunbo)."""
+        # Don't override a playing cloud video with slideshow themes
+        if self.controller.is_video_playing():
+            return
+
         themes = self.uc_theme_local.get_slideshow_themes()
         if not themes:
             self._slideshow_timer.stop()

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/src/trcc/services/display.py

@@ -399,6 +399,8 @@ class DisplayService:
 
     def _apply_adjustments(self, image: Any) -> Any:
         """Apply brightness, rotation, and split overlay to image."""
+        if self.brightness >= 100 and self.rotation == 0 and not self.split_mode:
+            return image
         image = ImageService.apply_brightness(image, self.brightness)
         image = ImageService.apply_rotation(image, self.rotation)
         image = self._apply_split_overlay(image)

{trcc_linux-5.0.4 → trcc_linux-5.0.6}/src/trcc/services/overlay.py

@@ -1,8 +1,8 @@
 """Overlay rendering service — config, mask, metrics → composited image.
 
-Pure Python (PIL), no Qt dependencies.
+Pure Python, no Qt dependencies.
 Orchestrates background, mask compositing, text overlays, and dynamic scaling.
-Font resolution delegated to FontResolver infrastructure.
+Rendering delegated to Renderer ABC (Strategy pattern) — PIL or QPainter.
 """
 from __future__ import annotations
 
@@ -10,10 +10,8 @@ import logging
 from pathlib import Path
 from typing import Any
 
-from PIL import Image, ImageDraw
-
-from ..adapters.infra.font_resolver import FontResolver
 from ..core.models import HardwareMetrics
+from .renderer import Renderer
 from .system import SystemService
 
 log = logging.getLogger(__name__)
@@ -29,12 +27,20 @@ class OverlayService:
     - Time/date with multiple format options
     - Hardware metrics (CPU, GPU, etc.)
     - Dynamic font/coordinate scaling across resolutions
+    - Overlay caching: re-render text+mask only when inputs change
     """
 
     # Base resolution for scaling (most common device)
     BASE_RESOLUTION = 320
 
-    def __init__(self, width: int = 320, height: int = 320) -> None:
+    def __init__(self, width: int = 320, height: int = 320,
+                 renderer: Renderer | None = None) -> None:
+        # Rendering backend (Strategy pattern)
+        if renderer is None:
+            from ..adapters.render.pil import PilRenderer
+            renderer = PilRenderer()
+        self._renderer: Renderer = renderer
+
         # Rendering state (public — tests + callers access these directly)
         self.width = width
         self.height = height
@@ -43,7 +49,6 @@ class OverlayService:
         self.theme_mask: Any = None
         self.theme_mask_position: tuple[int, int] = (0, 0)
         self.theme_mask_visible: bool = True  # Windows: isDrawMbImage
-        self._fonts = FontResolver()
         self.flash_skip_index: int = -1  # Windows shanPingCount
 
         # Format settings (matching Windows TRCC UCXiTongXianShiSub.cs)
@@ -63,14 +68,22 @@ class OverlayService:
         self._metrics: HardwareMetrics = HardwareMetrics()
         self._dc_data: dict[str, Any] | None = None
 
+        # Overlay cache: transparent layer with text + mask, re-rendered
+        # only when inputs change (~1/sec).  Per-frame cost drops from
+        # full text render to single alpha composite.
+        self._overlay_cache: Any | None = None
+        self._cache_key: tuple | None = None
+        self._overlay_has_content: bool = False  # True if mask/text was drawn
+
     # ── Resolution ───────────────────────────────────────────────────
 
     def set_resolution(self, w: int, h: int) -> None:
         """Update LCD resolution. Clears font cache and background."""
         self.width = w
         self.height = h
-        self._fonts.clear_cache()
+        self._renderer.clear_font_cache()
         self.background = None
+        self._invalidate_cache()
 
     # ── Enable / disable ─────────────────────────────────────────────
 
@@ -101,8 +114,8 @@ class OverlayService:
         if image.size == (self.width, self.height):
             self.background = image
         else:
-            self.background = image.copy().resize(
-                (self.width, self.height), Image.Resampling.LANCZOS
+            self.background = self._renderer.resize(
+                self._renderer.copy_surface(image), self.width, self.height
             )
 
     # ── Config ───────────────────────────────────────────────────────
@@ -110,6 +123,7 @@ class OverlayService:
     def set_config(self, config: dict) -> None:
         """Set overlay config dict directly."""
         self.config = config
+        self._invalidate_cache()
 
     def set_config_resolution(self, w: int, h: int) -> None:
         """Set the resolution the current config was designed for.
@@ -118,11 +132,13 @@ class OverlayService:
         designed for one resolution on a device with a different resolution.
         """
         self._config_resolution = (w, h)
+        self._invalidate_cache()
 
     def set_scale_enabled(self, enabled: bool) -> None:
         """Enable or disable dynamic font/coordinate scaling."""
         self._scale_enabled = enabled
-        self._fonts.clear_cache()
+        self._renderer.clear_font_cache()
+        self._invalidate_cache()
 
     def _get_scale_factor(self) -> float:
         """Calculate scale factor from config resolution to display resolution.
@@ -200,6 +216,7 @@ class OverlayService:
         if image is None:
             self.theme_mask = None
             self.theme_mask_position = (0, 0)
+            self._invalidate_cache()
             return
 
         if image.mode != 'RGBA':
@@ -214,6 +231,8 @@ class OverlayService:
         else:
             self.theme_mask_position = (0, 0)
 
+        self._invalidate_cache()
+
     def get_mask(self) -> tuple[Any, tuple[int, int] | None]:
         """Get current theme mask image and position."""
         return self.theme_mask, self.theme_mask_position
@@ -221,12 +240,14 @@ class OverlayService:
     def set_mask_visible(self, visible: bool) -> None:
         """Toggle mask visibility without destroying it (Windows SetDrawMengBan)."""
         self.theme_mask_visible = visible
+        self._invalidate_cache()
 
     # ── Temp unit ────────────────────────────────────────────────────
 
     def set_temp_unit(self, unit: int) -> None:
         """Set temperature display unit (0=Celsius, 1=Fahrenheit)."""
         self.temp_unit = unit
+        self._invalidate_cache()
 
     # ── Metrics ──────────────────────────────────────────────────────
 
@@ -234,25 +255,62 @@ class OverlayService:
         """Update system metrics for hardware overlay elements."""
         self._metrics = metrics
 
-    # ── Font resolution (delegated to FontResolver) ─────────────────
+    # ── Font resolution (delegated to Renderer) ──────────────────────
 
     @property
     def font_cache(self) -> dict:
-        """Font cache (delegates to FontResolver)."""
-        return self._fonts.cache
+        """Font cache (delegates to Renderer)."""
+        fonts = getattr(self._renderer, '_fonts', None)
+        return fonts.cache if fonts else {}
 
     @font_cache.setter
     def font_cache(self, value: dict) -> None:
-        self._fonts.cache = value
+        fonts = getattr(self._renderer, '_fonts', None)
+        if fonts:
+            fonts.cache = value
 
     def get_font(self, size: int, bold: bool = False,
                  font_name: str | None = None) -> Any:
         """Get font by name with fallback chain."""
-        return self._fonts.get(size, bold, font_name)
+        return self._renderer.get_font(size, bold, font_name)
 
     def _resolve_font_path(self, font_name: str, bold: bool = False) -> str | None:
         """Resolve font family name to file path."""
-        return self._fonts.resolve_path(font_name, bold)
+        fonts = getattr(self._renderer, '_fonts', None)
+        return fonts.resolve_path(font_name, bold) if fonts else None
+
+    # ── Overlay cache ────────────────────────────────────────────────
+
+    def _invalidate_cache(self) -> None:
+        """Force overlay re-render on next frame."""
+        self._overlay_cache = None
+        self._cache_key = None
+
+    def _build_cache_key(self, metrics: HardwareMetrics) -> tuple:
+        """Build cache key from all inputs that affect overlay appearance."""
+        return (
+            id(self.config),
+            id(self.theme_mask),
+            self.theme_mask_visible,
+            self.theme_mask_position,
+            self.time_format,
+            self.date_format,
+            self.temp_unit,
+            self.flash_skip_index,
+            self._get_scale_factor(),
+            self._metrics_hash(metrics),
+        )
+
+    def _metrics_hash(self, metrics: HardwareMetrics) -> int:
+        """Hash only the metric values referenced by current config."""
+        if not self.config or not isinstance(self.config, dict):
+            return 0
+        vals: list[Any] = []
+        for cfg in self.config.values():
+            if isinstance(cfg, dict) and 'metric' in cfg:
+                val = getattr(metrics, cfg['metric'], None)
+                vals.append(val)
+        return hash(tuple(vals))
 
     # ── Render ───────────────────────────────────────────────────────
 
@@ -276,12 +334,14 @@ class OverlayService:
         return self._render_overlay(m)
 
     def _render_overlay(self, metrics: HardwareMetrics | None = None) -> Any:
-        """Core PIL compositing — background + mask + text overlays.
+        """Compositing pipeline — background + cached overlay layer.
 
-        Optimized for video playback — returns background directly when
-        there's nothing to overlay (no mask, no config).
+        The overlay layer (mask + text) is cached and only re-rendered when
+        inputs change (~1/sec for metrics).  Per-frame cost is a single
+        alpha composite instead of full text rendering.
         """
         metrics = metrics or HardwareMetrics()
+        r = self._renderer
 
         # Fast path: no overlays, just return background as-is
         has_overlays = (
@@ -291,43 +351,67 @@ class OverlayService:
         if not has_overlays and self.background:
             return self.background
 
-        # Create base image
+        # Check cache
+        cache_key = self._build_cache_key(metrics)
+        if cache_key != self._cache_key or self._overlay_cache is None:
+            # Cache miss — render overlay layer to transparent surface
+            self._overlay_cache = self._render_overlay_layer(metrics, r)
+            self._cache_key = cache_key
+
+        # Fast path: overlay layer has no visible content (no mask, no text)
+        if not self._overlay_has_content and self.background:
+            return self.background
+
+        return self._composite_onto_background(r)
+
+    def _composite_onto_background(self, r: Renderer) -> Any:
+        """Composite cached overlay layer onto current background.
+
+        Overlay cache is RGBA; background is RGB.  PIL paste() with alpha
+        mask works directly on RGB — no RGBA round-trip needed.
+        """
         if self.background is None:
-            img = Image.new('RGBA', (self.width, self.height), (0, 0, 0, 0))
-        else:
-            img = self.background.copy()
-            if img.mode != 'RGBA':
-                img = img.convert('RGBA')
+            base = r.create_surface(self.width, self.height)
+            r.composite(base, self._overlay_cache, (0, 0))
+            return r.to_pil(r.convert_to_rgb(base))
+
+        base = r.copy_surface(r.from_pil(self.background))
+        r.composite(base, self._overlay_cache, (0, 0))
+        return r.to_pil(base)
 
-        # Apply theme mask (Windows: isDrawMbImage check)
+    def _render_overlay_layer(self, metrics: HardwareMetrics,
+                              r: Renderer) -> Any:
+        """Render mask + text to a transparent overlay surface.
+
+        This is the expensive operation — called only on cache miss.
+        Sets _overlay_has_content so callers can skip composite when empty.
+        """
+        self._overlay_has_content = False
+        overlay = r.create_surface(self.width, self.height)
+
+        # Apply theme mask
         if self.theme_mask and self.theme_mask_visible:
             scale = self._get_scale_factor()
+            mask_pil = self.theme_mask
+            self._overlay_has_content = True
             if abs(scale - 1.0) > 0.01:
-                mask_w = int(self.theme_mask.width * scale)
-                mask_h = int(self.theme_mask.height * scale)
-                scaled_mask = self.theme_mask.resize(
-                    (mask_w, mask_h), Image.Resampling.LANCZOS)
+                mask_w = int(mask_pil.width * scale)
+                mask_h = int(mask_pil.height * scale)
+                mask_surface = r.resize(r.from_pil(mask_pil), mask_w, mask_h)
                 pos_x = int(self.theme_mask_position[0] * scale)
                 pos_y = int(self.theme_mask_position[1] * scale)
-                img.paste(scaled_mask, (pos_x, pos_y), scaled_mask)
+                overlay = r.composite(overlay, mask_surface, (pos_x, pos_y))
             else:
-                img.paste(self.theme_mask, self.theme_mask_position, self.theme_mask)
-
-        # Convert to RGB before drawing text (matches Windows GenerateImage).
-        # Drawing on RGBA causes PIL to replace alpha at anti-aliased edges;
-        # compositing RGBA onto black creates dark fringes.
-        if img.mode == 'RGBA':
-            img = img.convert('RGB')
+                overlay = r.composite(
+                    overlay, r.from_pil(mask_pil), self.theme_mask_position)
 
         # Draw text overlays
-        draw = ImageDraw.Draw(img)
-
         if not self.config or not isinstance(self.config, dict):
-            return img
+            return overlay
 
         scale = self._get_scale_factor()
 
-        for elem_idx, (key, cfg) in enumerate(self.config.items()):
+        for elem_idx, (_key, cfg) in enumerate(self.config.items()):
             if not isinstance(cfg, dict) or not cfg.get('enabled', True):
                 continue
             if elem_idx == self.flash_skip_index:
@@ -362,10 +446,11 @@ class OverlayService:
 
             bold = font_cfg.get('style') == 'bold' if isinstance(font_cfg, dict) else False
             font_name = font_cfg.get('name') if isinstance(font_cfg, dict) else None
-            font = self.get_font(font_size, bold=bold, font_name=font_name)
-            draw.text((x, y), text, fill=color, font=font, anchor='mm')
+            font = r.get_font(font_size, bold=bold, font_name=font_name)
+            r.draw_text(overlay, x, y, text, color, font, anchor='mm')
+            self._overlay_has_content = True
 
-        return img
+        return overlay
 
     # ── DC data (lossless round-trip) ────────────────────────────────
 
@@ -388,3 +473,4 @@ class OverlayService:
         self.theme_mask = None
         self.theme_mask_position = (0, 0)
         self.theme_mask_visible = True
+        self._invalidate_cache()

trcc_linux-5.0.6/src/trcc/services/renderer.py

@@ -0,0 +1,68 @@
+"""Renderer port — ABC for overlay compositing backends.
+
+Strategy pattern: swap PIL (CPU) vs QPainter (GPU) without changing
+OverlayService logic.  Services stay pure Python — concrete renderers
+live in adapters/.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Renderer(ABC):
+    """Port: rendering backend for overlay compositing.
+
+    Concrete implementations:
+        - PilRenderer  (adapters/render/pil.py)  — PIL/Pillow, CPU-only
+        - QPainterRenderer (adapters/render/qt.py) — PySide6 QPainter, GPU-capable
+    """
+
+    @abstractmethod
+    def create_surface(self, width: int, height: int,
+                       color: tuple[int, ...] | None = None) -> Any:
+        """Create a new rendering surface (blank transparent or solid color)."""
+
+    @abstractmethod
+    def copy_surface(self, surface: Any) -> Any:
+        """Defensive copy of a surface."""
+
+    @abstractmethod
+    def convert_to_rgba(self, surface: Any) -> Any:
+        """Ensure surface has alpha channel."""
+
+    @abstractmethod
+    def convert_to_rgb(self, surface: Any) -> Any:
+        """Ensure surface is RGB (strip alpha)."""
+
+    @abstractmethod
+    def composite(self, base: Any, overlay: Any,
+                  position: tuple[int, int],
+                  mask: Any | None = None) -> Any:
+        """Alpha-composite *overlay* onto *base* at *position*."""
+
+    @abstractmethod
+    def resize(self, surface: Any, width: int, height: int) -> Any:
+        """Resize surface with high-quality resampling."""
+
+    @abstractmethod
+    def draw_text(self, surface: Any, x: int, y: int, text: str,
+                  color: str, font: Any, anchor: str = 'mm') -> None:
+        """Draw text onto surface at (x, y)."""
+
+    @abstractmethod
+    def get_font(self, size: int, bold: bool = False,
+                 font_name: str | None = None) -> Any:
+        """Resolve and cache a font at given size."""
+
+    @abstractmethod
+    def clear_font_cache(self) -> None:
+        """Flush font cache (e.g. after resolution change)."""
+
+    @abstractmethod
+    def to_pil(self, surface: Any) -> Any:
+        """Convert native surface → PIL Image (boundary output)."""
+
+    @abstractmethod
+    def from_pil(self, image: Any) -> Any:
+        """Convert PIL Image → native surface."""