frontengine 1.0.30__tar.gz → 1.0.32__tar.gz

{frontengine-1.0.30 → frontengine-1.0.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.30
+Version: 1.0.32
 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.30 → frontengine-1.0.32}/frontengine/show/pet/desktop_pet.py

@@ -1,7 +1,9 @@
+import json
 import random as _random_module
 import sys
 from datetime import datetime, timedelta
 from pathlib import Path
+from urllib.parse import urlparse
 from typing import Optional, Tuple
 
 from PySide6.QtCore import Qt, QRect, QTimer, QUrl, Signal
@@ -83,6 +85,10 @@ def scan_pet_pack(folder: str) -> dict:
     return result
 
 
+# 可以請寵物幫忙開啟的網址協定 / URL schemes the pet will open for you
+_WEB_SCHEMES = frozenset({"http", "https"})
+
+
 # 拖進寵物的檔案分類 / What a file dropped onto the pet means
 DROP_SPRITE = "sprite"  # 圖片或動作包 -> 換一套外觀
 DROP_FOOD = "food"      # 其他檔案 -> 當成食物餵給寵物
@@ -142,6 +148,55 @@ def classify_food(path) -> str:
     return FOOD_SNACK
 
 
+# 動作包設定檔：放在動作包資料夾裡，用來描述這隻寵物的個性與參數
+# Pack manifest: sits inside a pet pack folder describing that pet's traits.
+PACK_MANIFEST_NAME = "pet.json"
+_MANIFEST_NUMBERS = ("size", "speed")
+_MANIFEST_FLAGS = ("climb", "talk", "sit_on_windows")
+
+
+def read_pet_manifest(folder) -> dict:
+    """
+    讀取動作包裡的 pet.json（可選）。只取認得的欄位，型別不符就略過，
+    讀不到或格式錯誤一律回傳空 dict，讓動作包永遠不會弄壞寵物。
+
+    Read a pack's optional pet.json. Only known, well-typed fields are kept and
+    anything unreadable yields {}, so a pack can never break the pet.
+    """
+    manifest: dict = {}
+    try:
+        path = Path(folder) / PACK_MANIFEST_NAME
+        if not path.is_file():
+            return manifest
+        with path.open("r", encoding="utf-8") as handle:
+            raw = json.load(handle)
+    except (OSError, ValueError, TypeError):
+        return manifest
+    if not isinstance(raw, dict):
+        return manifest
+    for key in _MANIFEST_NUMBERS:
+        try:
+            if key in raw:
+                manifest[key] = max(1, int(raw[key]))
+        except (TypeError, ValueError):
+            continue
+    for key in _MANIFEST_FLAGS:
+        if isinstance(raw.get(key), bool):
+            manifest[key] = raw[key]
+    if isinstance(raw.get("name"), str):
+        manifest["name"] = raw["name"]
+    if isinstance(raw.get("sound"), str):
+        manifest["sound"] = raw["sound"]
+    lines = raw.get("lines")
+    if isinstance(lines, dict):
+        manifest["lines"] = {
+            str(pool): [str(line) for line in values if str(line).strip()]
+            for pool, values in lines.items()
+            if isinstance(values, list) and values
+        }
+    return manifest
+
+
 def derive_visual_state(dragging: bool, airborne: bool, surface: str, motion_state: str) -> str:
     """依目前情形推導應顯示的視覺狀態 / Derive which sprite state to show."""
     if dragging:
@@ -1101,9 +1156,21 @@ class DesktopPetWidget(BaseWidget):
         self._hunger = PetHunger(user_setting_dict.get("pet_hunger", 70))
         self._hunger_warned = False
         self._messages = self._load_messages()
+        # 動作包自帶的設定（可含台詞、速度、體型、音效）
+        # Traits shipped inside the pack (lines, speed, size, sound).
+        self.manifest = read_pet_manifest(self.image_path) if self.image_path.is_dir() else {}
+        self._apply_manifest()
         self._volume = max(0.0, min(1.0, float(volume)))
         self._sound: Optional[QSoundEffect] = None
-        self._init_sound(sound_path)
+        self._init_sound(self.manifest.get("sound_path", sound_path))
+        # 語音朗讀（可選，缺少 QtTextToSpeech 時自動停用）
+        # Optional spoken lines; disabled automatically without QtTextToSpeech.
+        self._speech = None
+        self._speak = False
+        # AI 對話（可選，需環境變數金鑰；預設關閉）
+        # Optional AI chat; needs an env-var key and is off by default.
+        self._chat_service = None
+        self._pending_chat_reply: Optional[str] = None
         self._sit_on_windows = bool(sit_on_windows)
         self._platform_tick = 0
         # 音訊視覺化：依可注入的音量 provider 脈動 / Audio-reactive pulse
@@ -1152,6 +1219,11 @@ class DesktopPetWidget(BaseWidget):
             language_wrapper.language_word_dict.get("pet_set_reminder", "Set reminder..."), self)
         self.reminder_action.triggered.connect(self._prompt_reminder)
         self.menu.addAction(self.reminder_action)
+        self.chat_action = QAction(
+            language_wrapper.language_word_dict.get("pet_chat_menu", "Talk to me..."), self)
+        self.chat_action.triggered.connect(self._prompt_chat)
+        self.chat_action.setVisible(False)  # shown only when a chat service is attached
+        self.menu.addAction(self.chat_action)
         self.close_action = QAction(language_wrapper.language_word_dict.get("control_center_close_all", "Close"), self)
         self.close_action.triggered.connect(self.close)
         self.menu.addAction(self.close_action)
@@ -1358,6 +1430,58 @@ class DesktopPetWidget(BaseWidget):
         if self._timeline_start is None:
             self._timeline_start = self._now_provider()
 
+    def _apply_manifest(self) -> None:
+        """套用動作包設定：台詞併入句庫，速度／體型／音效覆寫預設值。"""
+        if not self.manifest:
+            return
+        front_engine_logger.info(f"[DesktopPetWidget] pack manifest | {self.manifest}")
+        for pool, lines in (self.manifest.get("lines") or {}).items():
+            self._messages[pool] = list(lines)
+        if "speed" in self.manifest:
+            self.motion.speed = max(1, int(self.manifest["speed"]))
+        if "size" in self.manifest:
+            self._base_size = max(16, int(self.manifest["size"]))
+            self._apply_growth_size()
+        if "climb" in self.manifest:
+            self.motion.climb = bool(self.manifest["climb"])
+        if "talk" in self.manifest:
+            self._talk = bool(self.manifest["talk"])
+        sound = self.manifest.get("sound")
+        if sound:
+            candidate = self.image_path / sound
+            if candidate.is_file():
+                self.manifest["sound_path"] = str(candidate)
+
+    def set_speech_enabled(self, enabled: bool) -> bool:
+        """
+        開關語音朗讀；系統缺少 QtTextToSpeech 時回傳 False 並維持關閉。
+        Toggle spoken lines, returning False when QtTextToSpeech is unavailable.
+        """
+        if not enabled:
+            self._speak = False
+            return False
+        if self._speech is None:
+            try:
+                from PySide6.QtTextToSpeech import QTextToSpeech
+
+                self._speech = QTextToSpeech(self)
+            except Exception as error:  # pragma: no cover - optional Qt module
+                front_engine_logger.warning(f"[DesktopPetWidget] speech unavailable: {error!r}")
+                self._speech = None
+                self._speak = False
+                return False
+        self._speak = True
+        return True
+
+    def _speak_text(self, text: str) -> None:
+        """把台詞念出來（未啟用或失敗時安靜略過）。"""
+        if not self._speak or self._speech is None or not text:
+            return
+        try:
+            self._speech.say(text)
+        except Exception as error:  # pragma: no cover - speech backend guard
+            front_engine_logger.warning(f"[DesktopPetWidget] speech failed: {error!r}")
+
     def _load_messages(self) -> dict:
         d = language_wrapper.language_word_dict
 
@@ -1382,6 +1506,11 @@ class DesktopPetWidget(BaseWidget):
             "away": lines("pet_chatter_away", "Still there?|I'll nap till you're back~|Zzz..."),
             "levelup": lines("pet_chatter_levelup", "Level up!|I'm growing!|We're getting closer!"),
             "costume": lines("pet_chatter_costume", "New look!|How do I look?|Nice fit!"),
+            "fetch": lines("pet_chatter_fetch", "Fetch!|On it!|Opening that for you!"),
+            "focus_start": lines("pet_chatter_focus_start", "Focus time!|Let's concentrate!|I'll wait here."),
+            "focus_break": lines("pet_chatter_focus_break", "Break time!|Stretch a little!|Rest your eyes."),
+            "focus_back": lines("pet_chatter_focus_back", "Back to it!|Round two!|Let's keep going."),
+            "focus_done": lines("pet_chatter_focus_done", "Long break earned!|Great run!|Take a proper rest."),
             "tag": lines("pet_chatter_tag", "You're it!|Caught you!|My turn to chase!"),
             "any": lines("pet_chatter_any", "Hi there!|(^_^)|Keep going!"),
         }
@@ -1489,6 +1618,53 @@ class DesktopPetWidget(BaseWidget):
             return
         self.add_reminder(text.strip(), minutes)
 
+    # --- optional AI chat --------------------------------------------------
+    def set_chat_service(self, service) -> None:
+        """
+        接上 AI 對話服務（None 表示關閉）；服務不可用時右鍵選單不會出現該項目。
+        Attach the AI chat service (None disables it); the menu entry only
+        appears when the service is actually usable.
+        """
+        self._chat_service = service
+        usable = service is not None and bool(getattr(service, "available", lambda: False)())
+        self.chat_action.setVisible(usable)
+
+    def _prompt_chat(self) -> None:
+        """問使用者要說什麼，然後在背景等回覆（不卡 UI）。"""
+        from PySide6.QtWidgets import QInputDialog
+
+        if self._chat_service is None:
+            return
+        title = language_wrapper.language_word_dict.get("pet_chat_menu", "Talk to me...")
+        text, ok = QInputDialog.getText(
+            self, title, language_wrapper.language_word_dict.get("pet_chat_prompt", "Say something:"))
+        if not ok or not text.strip():
+            return
+        self.ask_chat(text.strip())
+
+    def ask_chat(self, message: str) -> None:
+        """送出一句話並在收到回覆時說出來；失敗則說一句抱歉。"""
+        if self._chat_service is None:
+            return
+        self.say(language_wrapper.language_word_dict.get("pet_chat_thinking", "Hmm, let me think..."))
+        self._chat_service.ask_async(message, self.handle_chat_reply)
+
+    def handle_chat_reply(self, reply: Optional[str]) -> None:
+        """處理回覆（可能來自背景執行緒）；空回覆時說一句抱歉。"""
+        if reply:
+            self._pending_chat_reply = reply
+        else:
+            self._pending_chat_reply = language_wrapper.language_word_dict.get(
+                "pet_chat_failed", "I couldn't reach my thoughts just now.")
+        # 回覆可能在背景執行緒抵達，透過計時器回到 UI 執行緒再顯示
+        # The reply may arrive off-thread; hop back to the UI thread to show it.
+        QTimer.singleShot(0, self._say_pending_chat_reply)
+
+    def _say_pending_chat_reply(self) -> None:
+        if self._pending_chat_reply:
+            self.say(self._pending_chat_reply)
+            self._pending_chat_reply = None
+
     def _init_sound(self, sound_path: Optional[str]) -> None:
         if not sound_path:
             return
@@ -1612,6 +1788,7 @@ class DesktopPetWidget(BaseWidget):
             text = pick_message(datetime.now().hour, self._chatter_rng, self._messages, mood=mood)
         if text:
             self._bubble.show_message(text, self)
+            self._speak_text(text)
 
     def _on_tick(self) -> None:
         if self._dragging:
@@ -1688,26 +1865,72 @@ class DesktopPetWidget(BaseWidget):
                 return local_path
         return None
 
+    @staticmethod
+    def dropped_link(mime_data) -> Optional[str]:
+        """
+        從拖曳資料取出網址（拖連結到寵物身上請牠幫忙開啟）；沒有則回傳 None。
+        Pull an http(s) link out of a drop so the pet can open it for you.
+        """
+        if mime_data is None:
+            return None
+        candidates = []
+        if mime_data.hasUrls():
+            candidates += [url.toString() for url in mime_data.urls() if not url.isLocalFile()]
+        if mime_data.hasText():
+            candidates.append(mime_data.text())
+        for candidate in candidates:
+            text = str(candidate or "").strip()
+            # 用網址解析判斷通訊協定，比字串開頭比對穩，也不必在程式碼裡寫死協定前綴。
+            # Parse the URL instead of prefix-matching: sturdier, and no scheme
+            # literals baked into the source.
+            try:
+                scheme = urlparse(text).scheme.lower()
+            except ValueError:
+                continue
+            if scheme in _WEB_SCHEMES:
+                return text
+        return None
+
+    def _accepts_drop(self, mime_data) -> bool:
+        return self.dropped_path(mime_data) is not None or self.dropped_link(mime_data) is not None
+
     def dragEnterEvent(self, event) -> None:
-        if self.dropped_path(event.mimeData()) is not None:
+        if self._accepts_drop(event.mimeData()):
             event.acceptProposedAction()
 
     def dragMoveEvent(self, event) -> None:
-        if self.dropped_path(event.mimeData()) is not None:
+        if self._accepts_drop(event.mimeData()):
             event.acceptProposedAction()
 
     def dropEvent(self, event) -> None:
         path = self.dropped_path(event.mimeData())
-        if path is None:
+        link = self.dropped_link(event.mimeData()) if path is None else None
+        if path is None and link is None:
             return
-        front_engine_logger.info(f"[DesktopPetWidget] dropEvent | path={path}")
+        front_engine_logger.info(f"[DesktopPetWidget] dropEvent | path={path}, link={link}")
         self.motion.wake()
-        if classify_drop(path) == DROP_SPRITE:
+        if link is not None:
+            self.fetch_link(link)
+        elif classify_drop(path) == DROP_SPRITE:
             self.change_sprite(path)
         else:
             self.feed(classify_food(path))
         event.acceptProposedAction()
 
+    def fetch_link(self, url: str) -> None:
+        """把拖進來的連結叼去瀏覽器開啟，並說一句 / Fetch a dropped link in the browser."""
+        from frontengine.utils.browser.browser import open_browser
+
+        front_engine_logger.info(f"[DesktopPetWidget] fetch_link | url={url}")
+        self._gain_affection(1)
+        pool = self._messages.get("fetch") or []
+        if pool:
+            self.say(pool[self._chatter_rng.randrange(len(pool))])
+        try:
+            open_browser(url)
+        except Exception as error:  # pragma: no cover - browser boundary
+            front_engine_logger.warning(f"[DesktopPetWidget] open_browser failed: {error!r}")
+
     def contextMenuEvent(self, event) -> None:
         self.menu.popup(event.globalPos())
 

frontengine-1.0.32/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.32/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)