frontengine 1.0.31__tar.gz → 1.0.33__tar.gz

{frontengine-1.0.31 → frontengine-1.0.33}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.31
+Version: 1.0.33
 Summary: FrontEngine is use-define frontview or only use like screen saver
 Author-email: JE-Chen <jechenmailman@gmail.com>
 Project-URL: Homepage, https://github.com/Intergration-Automation-Testing/FrontEngine

{frontengine-1.0.31 → frontengine-1.0.33}/frontengine/show/pet/desktop_pet.py

@@ -16,6 +16,12 @@ from frontengine.show.window_helpers import apply_overlay_window_flags
 from frontengine.user_setting.user_setting_file import user_setting_dict
 from frontengine.utils.audio_meter.audio_envelope import AudioEnvelope
 from frontengine.utils.logging.loggin_instance import front_engine_logger
+from frontengine.utils.power_mode.power_mode import scaled_interval
+from frontengine.utils.platform_info.platform_info import (
+    idle_seconds as platform_idle_seconds,
+    read_battery as platform_read_battery,
+    standable_windows,
+)
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
 
 # 行為模式 / Behaviour modes
@@ -212,75 +218,17 @@ def derive_visual_state(dragging: bool, airborne: bool, surface: str, motion_sta
     return STATE_WALK
 
 
-# 列舉可站立視窗時要略過的外殼視窗類別
-# Shell window classes skipped when enumerating standable windows.
-_PLATFORM_SKIP_CLASSES = {"WorkerW", "Progman", "Shell_TrayWnd", "Button"}
-
-
 def windows_platforms(exclude_hwnds=()) -> list:
     """
-    回傳目前可見頂層視窗的上緣做為可站立平台 (left, right, top_y)。僅 Windows
-    有效，其餘平台或發生錯誤時回傳空清單。
-    Return the top edges of visible top-level windows as standable platforms
-    (left, right, top_y). Windows only; returns [] elsewhere or on error.
+    回傳目前可站立的視窗上緣 (left, right, top_y)；各平台實作見 platform_info。
+    Standable window top edges; per-platform implementations live in platform_info.
     """
-    if sys.platform != "win32":
-        return []
-    try:
-        import ctypes
-        from ctypes import wintypes
-
-        user32 = ctypes.windll.user32
-        exclude = {int(h) for h in exclude_hwnds}
-        platforms: list = []
-
-        @ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
-        def _collect(hwnd, _lparam):
-            if int(hwnd) in exclude or not user32.IsWindowVisible(hwnd):
-                return True
-            rect = wintypes.RECT()
-            if not user32.GetWindowRect(hwnd, ctypes.byref(rect)):
-                return True
-            width = rect.right - rect.left
-            height = rect.bottom - rect.top
-            if width < 80 or height < 40:
-                return True
-            class_buffer = ctypes.create_unicode_buffer(64)
-            user32.GetClassNameW(hwnd, class_buffer, 64)
-            if class_buffer.value in _PLATFORM_SKIP_CLASSES:
-                return True
-            platforms.append((rect.left, rect.right, rect.top))
-            return True
-
-        user32.EnumWindows(_collect, 0)
-        return platforms
-    except Exception as error:  # pragma: no cover - Win32 boundary
-        front_engine_logger.warning(f"[windows_platforms] error: {error!r}")
-        return []
+    return standable_windows(exclude_hwnds)
 
 
 def idle_seconds():
-    """
-    回傳使用者未操作的秒數；無法取得時回傳 None。僅 Windows 實作。
-    Seconds since the last user input, or None when unavailable (Windows only).
-    """
-    if sys.platform != "win32":
-        return None
-    try:
-        import ctypes
-
-        class _LASTINPUTINFO(ctypes.Structure):
-            _fields_ = [("cbSize", ctypes.c_uint), ("dwTime", ctypes.c_uint)]
-
-        info = _LASTINPUTINFO()
-        info.cbSize = ctypes.sizeof(info)
-        if not ctypes.windll.user32.GetLastInputInfo(ctypes.byref(info)):
-            return None
-        elapsed_ms = ctypes.windll.kernel32.GetTickCount() - info.dwTime
-        return max(0.0, elapsed_ms / 1000.0)
-    except Exception as error:  # pragma: no cover - Win32 boundary
-        front_engine_logger.warning(f"[idle_seconds] error: {error!r}")
-        return None
+    """使用者未操作的秒數；取不到回傳 None（跨平台，見 platform_info）。"""
+    return platform_idle_seconds()
 
 
 class PetTimeline:
@@ -335,35 +283,8 @@ def pop_due_reminders(now, reminders):
 
 
 def read_battery():
-    """
-    回傳 (電量百分比, 是否充電中)；無法取得時回傳 None。僅 Windows 實作。
-    Return (percent, charging) or None when unavailable. Windows only.
-    """
-    if sys.platform != "win32":
-        return None
-    try:
-        import ctypes
-
-        class _SPS(ctypes.Structure):
-            _fields_ = [
-                ("ACLineStatus", ctypes.c_byte),
-                ("BatteryFlag", ctypes.c_byte),
-                ("BatteryLifePercent", ctypes.c_byte),
-                ("SystemStatusFlag", ctypes.c_byte),
-                ("BatteryLifeTime", ctypes.c_ulong),
-                ("BatteryFullLifeTime", ctypes.c_ulong),
-            ]
-
-        status = _SPS()
-        if not ctypes.windll.kernel32.GetSystemPowerStatus(ctypes.byref(status)):
-            return None
-        percent = status.BatteryLifePercent & 0xFF
-        if percent == 255:  # unknown / no battery
-            return None
-        return (int(percent), status.ACLineStatus == 1)
-    except Exception as error:  # pragma: no cover - Win32 boundary
-        front_engine_logger.warning(f"[read_battery] error: {error!r}")
-        return None
+    """回傳 (電量百分比, 是否充電中)；沒有電池或取不到回傳 None（跨平台）。"""
+    return platform_read_battery()
 
 
 def nearest_peer(center, peers):
@@ -1147,6 +1068,9 @@ class DesktopPetWidget(BaseWidget):
 
         self._timer = QTimer(self)
         self._timer.timeout.connect(self._on_tick)
+        # 省電模式與原始更新間隔 / Low-power state and the base tick interval
+        self._low_power = False
+        self._tick_interval_ms = 33
 
         # Speech bubbles / chatter / mood
         self._talk = bool(talk)
@@ -1417,6 +1341,12 @@ class DesktopPetWidget(BaseWidget):
             painter.drawPixmap(
                 QRect((self.width() - width) // 2, self.height() - height, width, height), pixmap)
 
+    def set_low_power(self, enabled: bool) -> None:
+        """省電模式：把移動更新拉慢（畫面較不順，但省電）。"""
+        self._low_power = bool(enabled)
+        if self._timer.isActive():
+            self._timer.start(scaled_interval(self._tick_interval_ms, self._low_power))
+
     def start_moving(self, bounds: Tuple[int, int, int, int], interval_ms: int = 33) -> None:
         front_engine_logger.info(f"[DesktopPetWidget] start_moving | bounds={bounds}")
         left, top, right, bottom = bounds
@@ -1424,7 +1354,8 @@ class DesktopPetWidget(BaseWidget):
         self.motion.x = float(left)
         self.motion.y = float(bottom - self.pet_size)
         self.move(int(self.motion.x), int(self.motion.y))
-        self._timer.start(max(10, int(interval_ms)))
+        self._tick_interval_ms = max(10, int(interval_ms))
+        self._timer.start(scaled_interval(self._tick_interval_ms, self._low_power))
         self._schedule_chatter()
         self._reminder_timer.start(10000)
         if self._timeline_start is None:

frontengine-1.0.33/frontengine/show/presentation/annotation_overlay.py

@@ -0,0 +1,153 @@
+"""
+螢幕塗鴉層：在畫面上用筆或螢光筆畫線、清除、復原。畫圖時需要接收滑鼠，
+所以它不是點擊穿透的；關閉塗鴉即恢復原本的操作。
+
+A screen annotation layer: draw over the screen with a pen or highlighter,
+undo, and clear. It has to take the mouse while you draw, so unlike the other
+overlays it is not click-through — turn it off and the screen is yours again.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from PySide6.QtCore import QPoint, Qt
+from PySide6.QtGui import QColor, QPainter, QPen
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.show.window_helpers import apply_overlay_window_flags
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+TOOL_PEN = "pen"
+TOOL_HIGHLIGHTER = "highlighter"
+TOOL_ERASER = "eraser"
+TOOLS = (TOOL_PEN, TOOL_HIGHLIGHTER, TOOL_ERASER)
+
+PEN_COLORS = (
+    ("Red", "#ff3b30"), ("Yellow", "#ffcc00"), ("Green", "#34c759"),
+    ("Blue", "#0a84ff"), ("Black", "#000000"), ("White", "#ffffff"),
+)
+DEFAULT_PEN_COLOR = "#ff3b30"
+MIN_WIDTH = 1
+MAX_WIDTH = 40
+
+
+def clamp_width(value, fallback: int = 4) -> int:
+    """把筆寬夾在可用範圍。"""
+    try:
+        return max(MIN_WIDTH, min(MAX_WIDTH, int(value)))
+    except (TypeError, ValueError):
+        return fallback
+
+
+def stroke_style(tool: str, color: str, width: int) -> Tuple[QColor, int]:
+    """
+    依工具決定實際的顏色與線寬：螢光筆是半透明的粗線，橡皮擦畫得更粗。
+    Per-tool colour and width: a highlighter is a wide translucent stroke, an
+    eraser is wider still.
+    """
+    pen_color = QColor(color)
+    if not pen_color.isValid():
+        pen_color = QColor(DEFAULT_PEN_COLOR)
+    stroke_width = clamp_width(width)
+    if tool == TOOL_HIGHLIGHTER:
+        pen_color.setAlpha(90)
+        stroke_width = clamp_width(stroke_width * 4)
+    elif tool == TOOL_ERASER:
+        stroke_width = clamp_width(stroke_width * 5)
+    return (pen_color, stroke_width)
+
+
+class AnnotationOverlay(BaseWidget):
+    """
+    塗鴉層：滑鼠拖曳畫線，支援筆／螢光筆／橡皮擦、復原與全部清除。
+    每一筆記成 (工具, 顏色, 線寬, 點清單)，因此復原與重繪都很單純。
+    """
+
+    def __init__(self, color: str = DEFAULT_PEN_COLOR, width: int = 4, tool: str = TOOL_PEN) -> None:
+        front_engine_logger.info(f"[AnnotationOverlay] Init | tool={tool}, color={color}, width={width}")
+        super().__init__()
+        self.opacity = 1.0
+        self.tool = tool if tool in TOOLS else TOOL_PEN
+        self.pen_color = color
+        self.pen_width = clamp_width(width)
+        self.strokes: List[dict] = []
+        self._current: Optional[dict] = None
+        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
+
+    def set_annotation_window_flag(self) -> None:
+        """塗鴉需要接收滑鼠，所以不使用點擊穿透。"""
+        apply_overlay_window_flags(self, show_on_bottom=False, allow_input=True)
+
+    def set_tool(self, tool: str) -> None:
+        if tool in TOOLS:
+            self.tool = tool
+
+    def set_pen(self, color: Optional[str] = None, width: Optional[int] = None) -> None:
+        if color is not None:
+            self.pen_color = color
+        if width is not None:
+            self.pen_width = clamp_width(width)
+
+    def clear(self) -> None:
+        """清掉所有筆畫 / Wipe every stroke."""
+        self.strokes = []
+        self._current = None
+        self.update()
+
+    def undo(self) -> bool:
+        """收回最後一筆；沒有筆畫可收時回傳 False。"""
+        if not self.strokes:
+            return False
+        self.strokes.pop()
+        self.update()
+        return True
+
+    # --- drawing ---------------------------------------------------------
+    def begin_stroke(self, point: QPoint) -> None:
+        self._current = {
+            "tool": self.tool, "color": self.pen_color, "width": self.pen_width, "points": [point],
+        }
+        self.strokes.append(self._current)
+
+    def extend_stroke(self, point: QPoint) -> None:
+        if self._current is not None:
+            self._current["points"].append(point)
+            self.update()
+
+    def end_stroke(self) -> None:
+        # 只有一個點的筆畫畫不出線，直接丟掉
+        # A single-point stroke draws nothing; drop it.
+        if self._current is not None and len(self._current["points"]) < 2:
+            self.strokes.remove(self._current)
+            self.update()
+        self._current = None
+
+    def mousePressEvent(self, event) -> None:
+        if event.button() == Qt.MouseButton.LeftButton:
+            self.begin_stroke(event.position().toPoint())
+        super().mousePressEvent(event)
+
+    def mouseMoveEvent(self, event) -> None:
+        self.extend_stroke(event.position().toPoint())
+        super().mouseMoveEvent(event)
+
+    def mouseReleaseEvent(self, event) -> None:
+        self.end_stroke()
+        super().mouseReleaseEvent(event)
+
+    def draw_content(self, painter: QPainter) -> None:
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+        for stroke in self.strokes:
+            points = stroke["points"]
+            if len(points) < 2:
+                continue
+            color, width = stroke_style(stroke["tool"], stroke["color"], stroke["width"])
+            if stroke["tool"] == TOOL_ERASER:
+                painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_Clear)
+            else:
+                painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_SourceOver)
+            painter.setPen(QPen(color, width, Qt.PenStyle.SolidLine,
+                                Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+            for start, end in zip(points, points[1:]):
+                painter.drawLine(start, end)
+        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_SourceOver)

frontengine-1.0.33/frontengine/show/presentation/cursor_effects.py

@@ -0,0 +1,166 @@
+"""
+游標強調層：在游標周圍畫一圈亮環、點擊時擴散漣漪，或把游標以外的區域壓暗
+（聚光燈）。教學、簡報與錄影時讓觀眾看得見滑鼠在哪。點擊穿透，不影響操作。
+
+Cursor emphasis: a ring around the pointer, a ripple when you click, or a
+spotlight that dims everything except a circle around the cursor — so an
+audience can follow the mouse during a demo. Click-through throughout.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from PySide6.QtCore import QPoint, QTimer, Qt
+from PySide6.QtGui import QColor, QCursor, QPainter, QRadialGradient
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+DEFAULT_RING_COLOR = "#ffcc00"
+DEFAULT_RING_RADIUS = 28
+DEFAULT_SPOTLIGHT_RADIUS = 160
+RIPPLE_STEPS = 12
+_MIN_RADIUS = 8
+_MAX_RADIUS = 600
+
+
+def clamp_radius(value, fallback: int = DEFAULT_RING_RADIUS) -> int:
+    """把半徑夾在看得見又不至於蓋滿螢幕的範圍。"""
+    try:
+        return max(_MIN_RADIUS, min(_MAX_RADIUS, int(value)))
+    except (TypeError, ValueError):
+        return fallback
+
+
+def ripple_radius(step: int, base_radius: int, steps: int = RIPPLE_STEPS) -> int:
+    """漣漪第 step 幀的半徑：從基準半徑往外擴散一倍。"""
+    total = max(1, int(steps))
+    progress = min(max(int(step), 0), total) / total
+    return int(clamp_radius(base_radius) * (1.0 + progress))
+
+
+def ripple_alpha(step: int, steps: int = RIPPLE_STEPS) -> int:
+    """漣漪第 step 幀的透明度：越擴散越淡，最後消失。"""
+    total = max(1, int(steps))
+    progress = min(max(int(step), 0), total) / total
+    return max(0, int(200 * (1.0 - progress)))
+
+
+class CursorEffectWidget(BaseWidget):
+    """
+    游標效果層：亮環、點擊漣漪、聚光燈可各自開關，全部跟著游標移動。
+    位置與點擊事件由外部注入（正式路徑接系統游標與全域滑鼠監聽），方便測試。
+    """
+
+    REFRESH_MS = 16
+
+    def __init__(self, ring: bool = True, ripple: bool = True, spotlight: bool = False,
+                 color: str = DEFAULT_RING_COLOR, radius: int = DEFAULT_RING_RADIUS,
+                 spotlight_radius: int = DEFAULT_SPOTLIGHT_RADIUS, dim: int = 55) -> None:
+        front_engine_logger.info(
+            f"[CursorEffectWidget] Init | ring={ring}, ripple={ripple}, spotlight={spotlight}")
+        super().__init__()
+        self.opacity = 1.0
+        self.show_ring = bool(ring)
+        self.show_ripple = bool(ripple)
+        self.show_spotlight = bool(spotlight)
+        self.color = QColor(color) if QColor(color).isValid() else QColor(DEFAULT_RING_COLOR)
+        self.radius = clamp_radius(radius)
+        self.spotlight_radius = clamp_radius(spotlight_radius, DEFAULT_SPOTLIGHT_RADIUS)
+        self.dim = max(0, min(90, int(dim)))
+        self.cursor_point = QPoint(0, 0)
+        self.ripples: List[dict] = []
+        self._cursor_provider = QCursor.pos
+        self._timer = QTimer(self)
+        self._timer.timeout.connect(self.tick)
+
+    def set_cursor_provider(self, provider) -> None:
+        """注入游標位置來源（測試用）。"""
+        self._cursor_provider = provider
+
+    def set_effects(self, ring: Optional[bool] = None, ripple: Optional[bool] = None,
+                    spotlight: Optional[bool] = None) -> None:
+        """開關個別效果。"""
+        if ring is not None:
+            self.show_ring = bool(ring)
+        if ripple is not None:
+            self.show_ripple = bool(ripple)
+        if spotlight is not None:
+            self.show_spotlight = bool(spotlight)
+        self.update()
+
+    def set_style(self, color: Optional[str] = None, radius: Optional[int] = None,
+                  spotlight_radius: Optional[int] = None, dim: Optional[int] = None) -> None:
+        """調整顏色、半徑與壓暗程度。"""
+        if color is not None:
+            candidate = QColor(color)
+            if candidate.isValid():
+                self.color = candidate
+        if radius is not None:
+            self.radius = clamp_radius(radius)
+        if spotlight_radius is not None:
+            self.spotlight_radius = clamp_radius(spotlight_radius, DEFAULT_SPOTLIGHT_RADIUS)
+        if dim is not None:
+            self.dim = max(0, min(90, int(dim)))
+        self.update()
+
+    def start_following(self, interval_ms: int = REFRESH_MS) -> None:
+        """開始跟隨游標。"""
+        self.tick()
+        self._timer.start(max(8, int(interval_ms)))
+
+    def add_ripple(self, point: Optional[QPoint] = None) -> None:
+        """在指定位置（預設為目前游標）加一圈點擊漣漪。"""
+        self.ripples.append({"point": QPoint(point or self.cursor_point), "step": 0})
+        self.update()
+
+    def tick(self) -> None:
+        """更新游標位置並推進漣漪動畫。"""
+        try:
+            position = self._cursor_provider()
+        except Exception:  # pragma: no cover - defensive around injected providers
+            return
+        self.cursor_point = QPoint(int(position.x()) - self.x(), int(position.y()) - self.y())
+        for ripple in list(self.ripples):
+            ripple["step"] += 1
+            if ripple["step"] > RIPPLE_STEPS:
+                self.ripples.remove(ripple)
+        self.update()
+
+    def draw_content(self, painter: QPainter) -> None:
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+        if self.show_spotlight:
+            self._draw_spotlight(painter)
+        if self.show_ring:
+            ring_color = QColor(self.color)
+            ring_color.setAlpha(120)
+            painter.setBrush(ring_color)
+            painter.setPen(Qt.PenStyle.NoPen)
+            painter.drawEllipse(self.cursor_point, self.radius, self.radius)
+        if self.show_ripple:
+            for ripple in self.ripples:
+                color = QColor(self.color)
+                color.setAlpha(ripple_alpha(ripple["step"]))
+                painter.setBrush(Qt.BrushStyle.NoBrush)
+                painter.setPen(color)
+                radius = ripple_radius(ripple["step"], self.radius)
+                painter.drawEllipse(ripple["point"], radius, radius)
+
+    def _draw_spotlight(self, painter: QPainter) -> None:
+        """把游標以外壓暗，中心保持透明，邊緣柔和過渡。"""
+        shade = QColor(0, 0, 0, int(255 * self.dim / 100.0))
+        gradient = QRadialGradient(self.cursor_point, self.spotlight_radius)
+        gradient.setColorAt(0.0, QColor(0, 0, 0, 0))
+        gradient.setColorAt(0.75, QColor(0, 0, 0, 0))
+        gradient.setColorAt(1.0, shade)
+        painter.fillRect(self.rect(), shade)
+        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_Source)
+        painter.setBrush(gradient)
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.drawEllipse(self.cursor_point, self.spotlight_radius, self.spotlight_radius)
+        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_SourceOver)
+
+    def closeEvent(self, event) -> None:
+        if self._timer.isActive():
+            self._timer.stop()
+        super().closeEvent(event)

frontengine-1.0.33/frontengine/show/presentation/keystroke_display.py

@@ -0,0 +1,161 @@
+"""
+按鍵顯示：把剛按下的按鍵顯示在畫面角落，做教學影片或直播時觀眾才知道你按了什麼。
+PowerToys 至今沒有內建這個功能，而本專案本來就有全域鍵盤監聽（pynput），
+所以只需要一層顯示。按鍵格式化是純函式，可獨立測試。
+
+Keystroke display: show what you just pressed in a screen corner, so viewers of
+a tutorial or stream can follow along. PowerToys still has no built-in version;
+this project already listens for global hotkeys, so only the display is new.
+The formatting is pure and independently testable.
+"""
+from __future__ import annotations
+
+import time
+from typing import List, Tuple
+
+from PySide6.QtCore import QRect, QTimer, Qt
+from PySide6.QtGui import QColor, QFont, QFontMetrics, QPainter
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+DEFAULT_HOLD_SECONDS = 2.0
+MAX_KEYS_SHOWN = 6
+
+# 修飾鍵的顯示名稱 / How modifier keys are shown
+_MODIFIER_NAMES = {
+    "ctrl": "Ctrl", "ctrl_l": "Ctrl", "ctrl_r": "Ctrl",
+    "alt": "Alt", "alt_l": "Alt", "alt_r": "Alt", "alt_gr": "AltGr",
+    "shift": "Shift", "shift_l": "Shift", "shift_r": "Shift",
+    "cmd": "Win", "cmd_l": "Win", "cmd_r": "Win",
+}
+# 特殊鍵的顯示名稱 / Friendlier names for special keys
+_SPECIAL_NAMES = {
+    "space": "Space", "enter": "Enter", "return": "Enter", "tab": "Tab",
+    "backspace": "Backspace", "delete": "Del", "esc": "Esc", "escape": "Esc",
+    "up": "↑", "down": "↓", "left": "←", "right": "→",
+    "page_up": "PgUp", "page_down": "PgDn", "home": "Home", "end": "End",
+}
+
+
+def format_key(name) -> str:
+    """
+    把按鍵名稱轉成畫面上好讀的字（修飾鍵、方向鍵、功能鍵各有寫法）。
+    Turn a key name into something readable on screen.
+    """
+    text = str(name or "").strip().strip("'")
+    if not text:
+        return ""
+    lowered = text.lower()
+    if lowered in _MODIFIER_NAMES:
+        return _MODIFIER_NAMES[lowered]
+    if lowered in _SPECIAL_NAMES:
+        return _SPECIAL_NAMES[lowered]
+    if lowered.startswith("key."):
+        return format_key(text[4:])
+    if len(text) == 1:
+        return text.upper()
+    if lowered.startswith("f") and lowered[1:].isdigit():
+        return text.upper()
+    return text.replace("_", " ").title()
+
+
+def format_combo(keys) -> str:
+    """把同時按著的按鍵組成 `Ctrl + Shift + S` 這種字串（去重、保留順序）。"""
+    parts: List[str] = []
+    for key in keys or ():
+        formatted = format_key(key)
+        if formatted and formatted not in parts:
+            parts.append(formatted)
+    return " + ".join(parts)
+
+
+def visible_keys(entries, now: float, hold_seconds: float = DEFAULT_HOLD_SECONDS,
+                 limit: int = MAX_KEYS_SHOWN) -> List[str]:
+    """
+    從 (文字, 時間) 清單裡挑出還沒過期的按鍵，最多顯示 limit 個（最新在後）。
+    The still-fresh entries from a list of (text, timestamp) pairs.
+    """
+    fresh = [text for text, stamp in entries or () if now - stamp <= max(0.1, float(hold_seconds))]
+    return fresh[-max(1, int(limit)):]
+
+
+class KeystrokeDisplayWidget(BaseWidget):
+    """
+    按鍵顯示層：把最近按下的按鍵排成一列顯示，過幾秒自動淡出。點擊穿透。
+    按鍵來源由外部推入（`push_keys`），因此不需要在這裡自己開監聽器。
+    """
+
+    REFRESH_MS = 100
+    PADDING = 12
+
+    def __init__(self, hold_seconds: float = DEFAULT_HOLD_SECONDS, font_size: int = 28,
+                 color: str = "#ffffff", background: str = "#000000") -> None:
+        front_engine_logger.info(f"[KeystrokeDisplayWidget] Init | hold={hold_seconds}s")
+        super().__init__()
+        self.opacity = 1.0
+        self.hold_seconds = max(0.2, float(hold_seconds))
+        self.text_color = QColor(color) if QColor(color).isValid() else QColor("#ffffff")
+        self.background_color = QColor(background) if QColor(background).isValid() else QColor("#000000")
+        self.font_size = max(8, int(font_size))
+        self.entries: List[Tuple[str, float]] = []
+        self._now = time.monotonic
+        self._timer = QTimer(self)
+        self._timer.timeout.connect(self._expire)
+
+    def set_clock(self, clock) -> None:
+        """注入時間來源（測試用）。"""
+        self._now = clock
+
+    def start(self, interval_ms: int = REFRESH_MS) -> None:
+        """開始定期清掉過期的按鍵。"""
+        self._timer.start(max(30, int(interval_ms)))
+
+    def push_keys(self, keys) -> None:
+        """
+        推入一次按鍵事件（單一鍵或組合鍵）；空的輸入忽略。
+        Record one keypress (single key or combination); blanks are ignored.
+        """
+        text = format_combo(keys if isinstance(keys, (list, tuple, set)) else [keys])
+        if not text:
+            return
+        self.entries.append((text, self._now()))
+        self.entries = self.entries[-(MAX_KEYS_SHOWN * 2):]
+        self.update()
+
+    def current_text(self) -> str:
+        """目前該顯示的字串。"""
+        return "   ".join(visible_keys(self.entries, self._now(), self.hold_seconds))
+
+    def _expire(self) -> None:
+        before = len(visible_keys(self.entries, self._now(), self.hold_seconds))
+        if before != len(self.entries):
+            self.entries = [
+                (text, stamp) for text, stamp in self.entries
+                if self._now() - stamp <= self.hold_seconds
+            ]
+            self.update()
+
+    def draw_content(self, painter: QPainter) -> None:
+        text = self.current_text()
+        if not text:
+            return
+        font = QFont(self.font().family(), self.font_size)
+        painter.setFont(font)
+        metrics = QFontMetrics(font)
+        width = metrics.horizontalAdvance(text) + self.PADDING * 2
+        height = metrics.height() + self.PADDING
+        box = QRect(max(0, (self.width() - width) // 2),
+                    max(0, self.height() - height - self.PADDING), width, height)
+        background = QColor(self.background_color)
+        background.setAlpha(170)
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.setBrush(background)
+        painter.drawRoundedRect(box, 8, 8)
+        painter.setPen(self.text_color)
+        painter.drawText(box, int(Qt.AlignmentFlag.AlignCenter), text)
+
+    def closeEvent(self, event) -> None:
+        if self._timer.isActive():
+            self._timer.stop()
+        super().closeEvent(event)