frontengine 1.0.56__tar.gz → 1.0.57__tar.gz

{frontengine-1.0.56 → frontengine-1.0.57}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.56
+Version: 1.0.57
 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.56 → frontengine-1.0.57}/frontengine/show/base_widget.py

@@ -26,6 +26,21 @@ class BaseWidget(QWidget):
         # Locked means click-through; unlocked overlays can be dragged into place.
         self.overlay_locked: bool = True
         self.overlay_lockable: bool = True
+        # 自己處理滑鼠的覆蓋層（畫筆、白板、框選、量尺、寵物）要把這個關掉。
+        # 不關的話，使用者一在上面拖曳，基底的「拖曳擺位」就把整個視窗一起搬走：
+        # 畫布滑出畫面，框選還會擷取到跟選取範圍不同的區域。
+        # Overlays that handle the mouse themselves - pen, whiteboard, region
+        # select, ruler, pet - switch this off. Otherwise dragging to draw also
+        # drags the window: the canvas slides off screen, and region capture
+        # grabs an area other than the one that was selected.
+        self.overlay_draggable: bool = True
+        # 位置記憶是以類別名稱為鍵的，也就是「同一類共用一份」。每個實例位置
+        # 各異的（便利貼、寵物）要關掉，否則會全部被拉到同一個位置與大小。
+        # The remembered geometry is keyed by class name, i.e. shared by every
+        # instance of that kind. Overlays whose instances each have their own
+        # place - sticky notes, the pet - switch it off, or they all snap to one
+        # position and size.
+        self.overlay_remembers_geometry: bool = True
         self.overlay_show_on_bottom: bool = False
         # 綠幕背景色：設了就以不透明色填滿背景，方便 OBS 去背
         # Chroma key colour: fills the background opaquely so OBS can key it out.
@@ -94,12 +109,13 @@ class BaseWidget(QWidget):
 
     # --- drag to position (only while unlocked) --------------------------
     def mousePressEvent(self, event) -> None:
-        if not self.overlay_locked and event.button() == Qt.MouseButton.LeftButton:
+        if self.overlay_draggable and not self.overlay_locked \
+                and event.button() == Qt.MouseButton.LeftButton:
             self._drag_origin = event.globalPosition().toPoint() - self.frameGeometry().topLeft()
         super().mousePressEvent(event)
 
     def mouseMoveEvent(self, event) -> None:
-        if not self.overlay_locked and self._drag_origin is not None:
+        if self.overlay_draggable and not self.overlay_locked and self._drag_origin is not None:
             self.move(event.globalPosition().toPoint() - self._drag_origin)
         super().mouseMoveEvent(event)
 
@@ -111,6 +127,8 @@ class BaseWidget(QWidget):
 
     def remember_geometry(self) -> None:
         """記住目前位置與大小，之後同類覆蓋層會開在同一處。"""
+        if not self.overlay_remembers_geometry:
+            return
         geometry = self.geometry()
         front_engine_logger.info(
             f"{self.__class__.__name__} remember_geometry | {geometry.x()},{geometry.y()} "
@@ -129,12 +147,19 @@ class BaseWidget(QWidget):
 
     def restore_saved_geometry(self) -> None:
         """若這類覆蓋層有記住的位置就套用（使用者拖曳過才會有）。"""
+        if not self.overlay_remembers_geometry:
+            return
         saved = get_overlay_geometry(self.__class__.__name__)
         if not saved:
             return
         try:
             if self.isFullScreen():
-                self.showNormal()
+                # 使用者這次明講要全螢幕（含「顯示在所有螢幕」），就別拿記住的
+                # 位置把它拉回視窗模式——那會讓每台螢幕的覆蓋層全擠到同一格。
+                # The caller explicitly asked for fullscreen (this is also how
+                # "show on all screens" presents each one). Dragging it back to a
+                # remembered rect would pile every screen's overlay onto one spot.
+                return
             self.setGeometry(*saved)
         except RuntimeError:  # pragma: no cover - widget closed mid-callback
             return

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/camera/camera_widget.py

@@ -138,6 +138,16 @@ class CameraWidget(BaseWidget):
                 self._camera.stop()
             except RuntimeError:  # pragma: no cover - already torn down
                 pass
+        # sink 的 parent 是這個 widget，所以只把 Python 參考設成 None 不會銷毀它。
+        # 每次重新 start()（例如換攝影機）都會多留一個還連著 _on_frame 的孤兒。
+        # The sink is parented to this widget, so dropping the Python reference
+        # does not destroy it: every restart - switching camera, say - leaves
+        # another orphan still connected to _on_frame.
+        if self._sink is not None:
+            try:
+                self._sink.deleteLater()
+            except RuntimeError:  # pragma: no cover - already torn down
+                pass
         self._camera = None
         self._session = None
         self._sink = None

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/canvas/whiteboard_widget.py

@@ -79,6 +79,11 @@ class WhiteboardWidget(BaseWidget):
         self.pen_width = max(1, int(width))
         self.opacity = 1.0
         self.overlay_lockable = False
+        # 白板自己處理拖曳（畫線與平移），基底的拖曳擺位會把整塊畫布搬走
+        # The whiteboard handles its own dragging - strokes and panning - and the
+        # base class's drag-to-position would carry the whole canvas off with it.
+        self.overlay_draggable = False
+        self.overlay_remembers_geometry = False
         self.strokes: List[Dict[str, Any]] = []
         self.zoom = 1.0
         self.offset = [0.0, 0.0]

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/capture/region_capture.py

@@ -65,6 +65,13 @@ class RegionCaptureWidget(BaseWidget):
         super().__init__()
         self.opacity = 1.0
         self.overlay_lockable = False
+        # 框選的拖曳就是選取範圍本身。讓基底也跟著搬視窗的話，事件座標會跟著
+        # 位移，最後擷取到的不是使用者框起來的那一塊。
+        # Here the drag is the selection. Letting the base class move the window
+        # too shifts the event coordinates, so what gets grabbed is not the area
+        # the user framed.
+        self.overlay_draggable = False
+        self.overlay_remembers_geometry = False
         self.origin: Optional[QPoint] = None
         self.current: Optional[QPoint] = None
         self.captured: Optional[QPixmap] = None

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/focus_shield/focus_shield_widget.py

@@ -84,12 +84,28 @@ class DimBackgroundWidget(BaseWidget):
         geometry = self.geometry()
         return (geometry.x(), geometry.y(), geometry.width(), geometry.height())
 
+    def _to_logical(self, rect: Optional[Tuple[int, int, int, int]]):
+        """
+        把 Win32 的視窗矩形換算成 Qt 的邏輯座標。GetWindowRect 給的是實體像素，
+        screen_rect() 給的是邏輯像素，顯示縮放不是 100% 時兩者對不起來：在 150%
+        的螢幕上，最大化的視窗會算成比整個螢幕還大，結果一塊都不壓暗。
+        Convert a Win32 window rect into Qt's logical coordinates. GetWindowRect
+        reports physical pixels while screen_rect() is logical, and the two
+        disagree at any scaling other than 100%: on a 150% display a maximised
+        window measures larger than the whole screen, so nothing gets dimmed.
+        """
+        if rect is None:
+            return None
+        ratio = self.devicePixelRatio() or 1.0
+        return tuple(int(round(value / ratio)) for value in rect)
+
     def refresh(self) -> None:
         """重新計算要壓暗的區塊。"""
         try:
             active = self._window_provider()
         except Exception:  # pragma: no cover - defensive around providers
             active = None
+        active = self._to_logical(active)
         rects = surrounding_rects(self.screen_rect(), active)
         origin_x, origin_y = self.x(), self.y()
         # 換算成本視窗的座標系 / Convert to this widget's own coordinates

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/gif/paint_gif.py

@@ -39,6 +39,12 @@ class GifWidget(BaseWidget):
         self.speed = speed
         self.movie.setSpeed(self.speed)
 
+    def closeEvent(self, event) -> None:
+        # 關掉之後還在解碼就是白燒 CPU，畫面早就不見了
+        # A movie still decoding after the overlay is gone is pure wasted CPU.
+        self.movie.stop()
+        super().closeEvent(event)
+
     def draw_content(self, painter: QPainter) -> None:
         current_gif_frame = self.movie.currentPixmap()
         painter.drawPixmap(

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/image/paint_image.py

@@ -18,10 +18,14 @@ class ImageWidget(BaseWidget):
     def __init__(self, image_path: str, draw_location_x: int = 0, draw_location_y: int = 0):
         super().__init__(draw_location_x, draw_location_y)
         self.image_path: Path = Path(image_path)
+        # 先給一張空圖，路徑失效時 paintEvent 才不會撞上未定義的屬性
+        # Start from an empty image so a bad path cannot leave paintEvent
+        # facing an attribute that was never assigned.
+        self.image: QImage = QImage()
 
         if self.image_path.exists() and self.image_path.is_file():
             front_engine_logger.info(f"Loading image file: {self.image_path}")
-            self.image: QImage = QImage(str(self.image_path))
+            self.image = QImage(str(self.image_path))
             self.resize(self.image.size())
         else:
             message_box: QMessageBox = QMessageBox(self)
@@ -45,6 +49,8 @@ class ImageWidget(BaseWidget):
         return True
 
     def draw_content(self, painter: QPainter) -> None:
+        if self.image.isNull():
+            return
         painter.drawImage(
             QRect(self.draw_location_x, self.draw_location_y, self.width(), self.height()),
             self.image

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/load/load_someone_make_ui.py

@@ -1,12 +1,30 @@
 from typing import Optional, List
 
-from PySide6.QtGui import QScreen
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QGuiApplication
 from PySide6.QtUiTools import QUiLoader
 from PySide6.QtWidgets import QWidget
 
 from frontengine.utils.exception.exceptions import FrontEngineLoadUIException
 from frontengine.utils.logging.loggin_instance import front_engine_logger
 
+# 載入的視窗沒有 parent，Python 這邊不留參考就會立刻被回收，視窗根本不會出現。
+# A loaded window has no parent, so without a reference on the Python side it is
+# collected the moment this function returns and never appears at all.
+_loaded_ui_widgets: List[QWidget] = []
+
+
+def _forget_closed_ui() -> None:
+    """把已被 Qt 銷毀的視窗從清單剔除，免得一直累積。"""
+    alive: List[QWidget] = []
+    for widget in _loaded_ui_widgets:
+        try:
+            widget.isVisible()
+        except RuntimeError:  # 底層 C++ 物件已消滅 / underlying C++ object is gone
+            continue
+        alive.append(widget)
+    _loaded_ui_widgets[:] = alive
+
 
 def load_extend_ui_file(ui_path: str, show_all_screen: bool = False) -> None:
     """
@@ -19,19 +37,24 @@ def load_extend_ui_file(ui_path: str, show_all_screen: bool = False) -> None:
     front_engine_logger.info(
         f"[load_extend_ui_file] ui_path={ui_path}, show_all_screen={show_all_screen}"
     )
-
-    ui: QWidget = load_ui_file(ui_path)
+    _forget_closed_ui()
 
     if show_all_screen:
-        ui.showFullScreen()
+        # 一個 widget 不可能同時待在多台螢幕上，每台各載入一份
+        # One widget cannot sit on several screens at once, so load one per screen.
+        for screen in QGuiApplication.screens():
+            _present_ui(load_ui_file(ui_path), screen.availableGeometry().topLeft())
     else:
-        # 取得所有螢幕並在每個螢幕上顯示 UI
-        # Get all monitors and display UI on each
-        monitors: List[QScreen] = QScreen.virtualSiblings(ui.screen())
-        for screen in monitors:
-            monitor_geometry = screen.availableGeometry()
-            ui.move(monitor_geometry.left(), monitor_geometry.top())
-            ui.showFullScreen()
+        _present_ui(load_ui_file(ui_path), None)
+
+
+def _present_ui(ui: QWidget, top_left) -> None:
+    """全螢幕顯示一個載入好的視窗，並保留參考直到它被關閉。"""
+    ui.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
+    if top_left is not None:
+        ui.move(top_left)
+    ui.showFullScreen()
+    _loaded_ui_widgets.append(ui)
 
 
 def load_ui_file(ui_path: str) -> QWidget:

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/measure/measure_widget.py

@@ -67,6 +67,10 @@ class MeasureWidget(BaseWidget):
         self.color_format = color_format
         self.opacity = 1.0
         self.overlay_lockable = False
+        # 量測靠的是螢幕座標，覆蓋層一被拖走就量錯
+        # Measuring is in screen coordinates; dragging the overlay falsifies it.
+        self.overlay_draggable = False
+        self.overlay_remembers_geometry = False
         self.points: List[QPoint] = []
         self.cursor_point = QPoint(0, 0)
         self.picked_color: Optional[QColor] = None
@@ -138,13 +142,21 @@ class MeasureWidget(BaseWidget):
             self.readout = self.color_text(color)
             self.update()
             return self.readout
-        self.points.append(QPoint(point))
         needed = 2 if self.mode == MODE_RULER else 3
+        if len(self.points) >= needed:
+            # 上一次已經量完了，這一下是新一次量測的第一點。先前的寫法是把新的
+            # 點加進去、拿舊的點算完再截掉，等於每一次新點擊都重算並重新複製
+            # 同一個舊結果——量尺變成只能用一次。
+            # The previous measurement is finished, so this click starts the next
+            # one. The old code appended the new point, measured the *old* ones
+            # and truncated the new one away, so every later click recomputed and
+            # re-copied the same stale result: the ruler worked exactly once.
+            self.points.clear()
+        self.points.append(QPoint(point))
         if len(self.points) < needed:
             self.update()
             return None
         self.readout = self._finish_measurement()
-        self.points = self.points[:needed]
         self.update()
         return self.readout
 

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/notes/sticky_note_widget.py

@@ -91,6 +91,12 @@ class StickyNoteWidget(BaseWidget):
         # 要打字就不能點擊穿透，也就不提供鎖定
         # Typing needs the mouse and keyboard, so this one is never lockable.
         self.overlay_lockable = False
+        # 便利貼可以拖，但每張各有各的位置，所以不用「同類共用一份」的位置記憶。
+        # 每張的位置與大小是由 note_state() 各自存的。
+        # Notes are draggable, but each has its own place, so the class-wide
+        # geometry memory does not apply: note_state() persists each note's own
+        # position and size.
+        self.overlay_remembers_geometry = False
         self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground, False)
 
         self.text_edit = QTextEdit(self)

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/overlay_factory.py

@@ -11,7 +11,14 @@ from frontengine.show.video.video_player import VideoWidget
 from frontengine.show.web.webview import WebWidget
 
 
-def _normalize_opacity(value: Optional[Any], default: float = 0.2) -> float:
+def _normalize_percent(value: Optional[Any], default: float) -> float:
+    """
+    場景 JSON 裡的百分比欄位（不透明度、音量、播放速率）轉成 0.0-1.0。
+    沒填就用 default——default 已經是最終比例，不要再除以 100。
+    Turn a percentage field from the scene JSON (opacity, volume, play rate)
+    into a 0.0-1.0 ratio. A missing field falls back to `default`, which is
+    already the final ratio and must not be divided again.
+    """
     try:
         return float(value) / 100 if value is not None else default
     except (ValueError, TypeError):
@@ -25,11 +32,18 @@ def _normalize_int(value: Optional[Any], default: int) -> int:
         return default
 
 
-def _normalize_float(value: Optional[Any], default: float) -> float:
-    try:
-        return float(value) if value is not None else default
-    except (ValueError, TypeError):
-        return default
+def _require(setting_dict: Dict[str, Any], key: str, kind: str) -> str:
+    """
+    取出必要欄位。場景 JSON 是使用者自己編輯／外部提供的，缺欄位就明講，
+    不要把 None 一路送進 Path() 或 QWebEngineView.load() 才炸在深處。
+    Fetch a required field. Scene JSON is hand-edited or third-party, so say
+    what is missing here instead of letting None reach Path() or
+    QWebEngineView.load() and blow up somewhere deeper.
+    """
+    value = setting_dict.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"Scene entry of type '{kind}' is missing a valid '{key}'")
+    return value
 
 
 class OverlayFactory(ABC):
@@ -46,31 +60,30 @@ class OverlayFactory(ABC):
 
 class ImageOverlayFactory(OverlayFactory):
     def create(self, setting_dict: Dict[str, Any]) -> QWidget:
-        widget = ImageWidget(setting_dict.get("file_path"))
-        widget.set_ui_variable(_normalize_opacity(setting_dict.get("opacity")))
+        widget = ImageWidget(_require(setting_dict, "file_path", "image"))
+        widget.set_ui_variable(_normalize_percent(setting_dict.get("opacity"), 0.2))
         return widget
 
 
 class GifOverlayFactory(OverlayFactory):
     def create(self, setting_dict: Dict[str, Any]) -> QWidget:
-        widget = GifWidget(setting_dict.get("file_path"))
+        widget = GifWidget(_require(setting_dict, "file_path", "gif"))
         widget.set_gif_variable(_normalize_int(setting_dict.get("speed"), 100))
-        widget.set_ui_variable(_normalize_opacity(setting_dict.get("opacity")))
+        widget.set_ui_variable(_normalize_percent(setting_dict.get("opacity"), 0.2))
         return widget
 
 
 class SoundOverlayFactory(OverlayFactory):
     def create(self, setting_dict: Dict[str, Any]) -> QWidget:
-        widget = SoundPlayer(setting_dict.get("file_path"))
-        volume = _normalize_float(setting_dict.get("volume"), 1.0) / 100
-        widget.set_player_variable(volume)
+        widget = SoundPlayer(_require(setting_dict, "file_path", "sound"))
+        widget.set_player_variable(_normalize_percent(setting_dict.get("volume"), 1.0))
         return widget
 
 
 class TextOverlayFactory(OverlayFactory):
     def create(self, setting_dict: Dict[str, Any]) -> QWidget:
-        widget = TextWidget(setting_dict.get("text"))
-        widget.set_ui_variable(_normalize_opacity(setting_dict.get("opacity")))
+        widget = TextWidget(_require(setting_dict, "text", "text"))
+        widget.set_ui_variable(_normalize_percent(setting_dict.get("opacity"), 0.2))
         widget.set_font_variable(_normalize_int(setting_dict.get("font_size"), 100))
         widget.set_alignment(setting_dict.get("alignment", "Center"))
         return widget
@@ -78,19 +91,19 @@ class TextOverlayFactory(OverlayFactory):
 
 class VideoOverlayFactory(OverlayFactory):
     def create(self, setting_dict: Dict[str, Any]) -> QWidget:
-        widget = VideoWidget(setting_dict.get("file_path"))
-        opacity = _normalize_opacity(setting_dict.get("opacity"))
-        volume = _normalize_float(setting_dict.get("volume"), 1.0) / 100
-        play_rate = _normalize_float(setting_dict.get("play_rate"), 1.0) / 100
-        widget.set_ui_variable(opacity)
-        widget.set_player_variable(play_rate, volume)
+        widget = VideoWidget(_require(setting_dict, "file_path", "video"))
+        widget.set_ui_variable(_normalize_percent(setting_dict.get("opacity"), 0.2))
+        widget.set_player_variable(
+            _normalize_percent(setting_dict.get("play_rate"), 1.0),
+            _normalize_percent(setting_dict.get("volume"), 1.0),
+        )
         return widget
 
 
 class WebOverlayFactory(OverlayFactory):
     def create(self, setting_dict: Dict[str, Any]) -> QWidget:
-        widget = WebWidget(setting_dict.get("url"))
-        widget.set_ui_variable(_normalize_opacity(setting_dict.get("opacity")))
+        widget = WebWidget(_require(setting_dict, "url", "web"))
+        widget.set_ui_variable(_normalize_percent(setting_dict.get("opacity"), 0.2))
         return widget
 
 

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/particle/particle_ui.py

@@ -15,7 +15,7 @@ from OpenGL.GL import (
     glTexCoord2f, glTexImage2D, glTexParameteri, glTranslatef, glVertex2f, glViewport,
 )
 from PySide6.QtCore import Qt, QTimer
-from PySide6.QtGui import QSurfaceFormat, QPixmap
+from PySide6.QtGui import QImage, QSurfaceFormat, QPixmap
 from PySide6.QtOpenGLWidgets import QOpenGLWidget
 
 from frontengine.show.window_helpers import apply_overlay_window_flags, load_overlay_icon
@@ -48,6 +48,7 @@ class ParticleOpenGLWidget(QOpenGLWidget):
 
         self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
         self.setAttribute(Qt.WidgetAttribute.WA_NoSystemBackground)
+        self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
         self.setAutoFillBackground(False)
         load_overlay_icon(self)
 
@@ -61,7 +62,13 @@ class ParticleOpenGLWidget(QOpenGLWidget):
             Qt.AspectRatioMode.KeepAspectRatio,
             Qt.TransformationMode.SmoothTransformation
         )
-        self.image = scaled_pixmap.toImage()
+        # QPixmap.toImage() 給的是 ARGB32（記憶體順序 BGRA），直接當成 GL_RGBA 上傳
+        # 會把紅藍對調。轉成 RGBA8888 才和下面的 glTexImage2D 對得起來，
+        # 順帶去掉預乘 alpha，符合 GL_SRC_ALPHA 混色的預期。
+        # toImage() hands back ARGB32, i.e. BGRA in memory; uploading that as
+        # GL_RGBA swaps red and blue. RGBA8888 matches the glTexImage2D call
+        # below and is un-premultiplied, which is what GL_SRC_ALPHA expects.
+        self.image = scaled_pixmap.toImage().convertToFormat(QImage.Format.Format_RGBA8888)
 
         self.particle_count = particle_count
         self.particle_direction = particle_direction
@@ -99,6 +106,11 @@ class ParticleOpenGLWidget(QOpenGLWidget):
         glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA)
         glEnable(GL_TEXTURE_2D)
 
+        if self.image.isNull():
+            # 沒有材質就別上傳 0x0 的貼圖，畫的時候直接跳過
+            # No texture: skip the 0x0 upload and let paintGL bail out.
+            return
+
         w, h = self.image.width(), self.image.height()
 
         self.texture_id = glGenTextures(1)
@@ -144,6 +156,9 @@ class ParticleOpenGLWidget(QOpenGLWidget):
         glClearColor(0, 0, 0, 0)
         glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
 
+        if self.texture_id is None:
+            return
+
         glBindTexture(GL_TEXTURE_2D, self.texture_id)
         glColor4f(1, 1, 1, self.opacity)
 
@@ -175,3 +190,10 @@ class ParticleOpenGLWidget(QOpenGLWidget):
 
     def set_ui_window_flag(self, show_on_bottom: bool = False) -> None:
         apply_overlay_window_flags(self, show_on_bottom=show_on_bottom)
+
+    def closeEvent(self, event) -> None:
+        # 關掉之後還在跑 60Hz 更新上萬顆粒子，畫面卻早就沒了
+        # Without this the 60 Hz update keeps churning through every particle
+        # long after the overlay has gone from the screen.
+        self.timer.stop()
+        super().closeEvent(event)

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/pet/desktop_pet.py

@@ -1094,6 +1094,16 @@ class DesktopPetWidget(BaseWidget):
         )
         super().__init__()
         self.opacity = 1.0
+        # 寵物自己處理拖曳，位置與大小也由 PetMotion 決定。交給基底記憶的話，
+        # 拖過一次之後那個「位置＋大小」會套到之後每一隻寵物身上——尺寸下拉選單
+        # 就等於失效：新寵物被悄悄縮回舊尺寸，碰撞判定卻還用新的大小。
+        # The pet drags itself and PetMotion owns its geometry. Letting the base
+        # class remember it means one drag pins that position and size onto every
+        # later pet - which silently disables the size combobox: a new pet is
+        # resized back while its collision box still uses the size that was asked
+        # for.
+        self.overlay_draggable = False
+        self.overlay_remembers_geometry = False
         # 基礎尺寸依已存等級放大 / Base size grown by the persisted level.
         self._base_size: int = max(16, int(size))
         self._growth = PetGrowth(user_setting_dict.get("pet_affection", 0))
@@ -1189,7 +1199,9 @@ class DesktopPetWidget(BaseWidget):
         self.clone_action.triggered.connect(self.clone_requested.emit)
         self.menu.addAction(self.clone_action)
         self.feed_action = QAction(language_wrapper.language_word_dict.get("pet_feed", "Feed"), self)
-        self.feed_action.triggered.connect(self.feed)
+        # triggered 會送出 checked(bool)，直接接的話 feed 收到的 kind 是 False
+        # triggered emits checked(bool), which would arrive as feed's `kind`.
+        self.feed_action.triggered.connect(lambda: self.feed())
         self.menu.addAction(self.feed_action)
         self.status_action = QAction(language_wrapper.language_word_dict.get("pet_status", "Status"), self)
         self.status_action.triggered.connect(self.show_status)
@@ -1659,9 +1671,15 @@ class DesktopPetWidget(BaseWidget):
         else:
             self._pending_chat_reply = language_wrapper.language_word_dict.get(
                 "pet_chat_failed", "I couldn't reach my thoughts just now.")
-        # 回覆可能在背景執行緒抵達，透過計時器回到 UI 執行緒再顯示
+        # 回覆可能在背景執行緒抵達，透過計時器回到 UI 執行緒再顯示。
+        # 一定要傳 context 物件（這裡是 self）：兩個參數的 singleShot 會把計時器
+        # 建在呼叫端那條執行緒上，而那條執行緒沒有事件迴圈，計時器永遠不會觸發
+        # ——寵物就一直停在「讓我想想…」，回覆再也不會出現。
         # The reply may arrive off-thread; hop back to the UI thread to show it.
-        QTimer.singleShot(0, self._say_pending_chat_reply)
+        # The context object (self) is essential: the two-argument singleShot
+        # creates the timer on the calling thread, which has no event loop, so it
+        # never fires - the pet stays on "let me think..." and the answer is lost.
+        QTimer.singleShot(0, self, self._say_pending_chat_reply)
 
     def _say_pending_chat_reply(self) -> None:
         if self._pending_chat_reply:

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/presentation/annotation_overlay.py

@@ -67,6 +67,14 @@ class AnnotationOverlay(BaseWidget):
         front_engine_logger.info(f"[AnnotationOverlay] Init | tool={tool}, color={color}, width={width}")
         super().__init__()
         self.opacity = 1.0
+        # 這一層的滑鼠是拿來畫畫的：不能被基底拖走，也不能被「鎖定覆蓋層」
+        # 變成點擊穿透——那會讓畫筆整個失效，而畫好的線還留在畫面上。
+        # The mouse here is the pen: the base class must not drag the window with
+        # it, and "lock overlays" must not make it click-through - that kills the
+        # pen outright while the strokes stay frozen on screen.
+        self.overlay_lockable = False
+        self.overlay_draggable = False
+        self.overlay_remembers_geometry = False
         self.tool = tool if tool in TOOLS else TOOL_PEN
         self.pen_color = color
         self.pen_width = clamp_width(width)

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/presentation/cursor_effects.py

@@ -111,7 +111,14 @@ class CursorEffectWidget(BaseWidget):
 
     def add_ripple(self, point: Optional[QPoint] = None) -> None:
         """在指定位置（預設為目前游標）加一圈點擊漣漪。"""
-        self.ripples.append({"point": QPoint(point or self.cursor_point), "step": 0})
+        # QPoint 的真值判斷是 isNull()，所以 bool(QPoint(0, 0)) 是 False：
+        # 用 `point or ...` 的話，剛好點在覆蓋層左上角的那一下會被當成沒給座標，
+        # 漣漪畫到上一次輪詢到的游標位置去。
+        # QPoint's truthiness is isNull(), so bool(QPoint(0, 0)) is False: with
+        # `point or ...` a click exactly on the overlay's top-left corner reads as
+        # "no point given" and the ripple lands on the last polled cursor spot.
+        origin = self.cursor_point if point is None else point
+        self.ripples.append({"point": QPoint(origin), "step": 0})
         self.update()
 
     def tick(self) -> None:

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/presentation/keystroke_display.py

@@ -128,12 +128,20 @@ class KeystrokeDisplayWidget(BaseWidget):
         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
-            ]
+        # 拿還沒過期的「全部」數量來比，不要用 visible_keys——它只回傳最多
+        # MAX_KEYS_SHOWN 筆，一旦按超過那個數量，這個比較就永遠不相等，
+        # 每 100ms 都會重建清單並重畫一次，其實什麼都沒過期。
+        # Compare against the full count of unexpired entries, not visible_keys:
+        # that returns at most MAX_KEYS_SHOWN, so past that many keys the test is
+        # never equal and every 100 ms tick rebuilds the list and repaints with
+        # nothing actually having expired.
+        now = self._now()
+        fresh = [
+            (text, stamp) for text, stamp in self.entries
+            if now - stamp <= self.hold_seconds
+        ]
+        if len(fresh) != len(self.entries):
+            self.entries = fresh
             self.update()
 
     def draw_content(self, painter: QPainter) -> None:

{frontengine-1.0.56 → frontengine-1.0.57}/frontengine/show/presentation/magnifier.py

@@ -86,14 +86,26 @@ class MagnifierWidget(BaseWidget):
 
     @staticmethod
     def _grab_screen(rect: QRect) -> Optional[QPixmap]:
-        """用 Qt 擷取指定螢幕區域；沒有可用螢幕時回傳 None。"""
-        screen = QGuiApplication.primaryScreen()
+        """
+        擷取指定的螢幕區域。要用「那塊區域所在的那台螢幕」去擷取，不是主螢幕：
+        放大鏡可以被指定開在副螢幕上，寫死主螢幕的話，游標移到另一台時擷取到的
+        是完全不相干的位置。
+        Grab a screen region using the screen that region is actually on, not the
+        primary one: the magnifier can be placed on a secondary display, and
+        hard-coding the primary grabs somewhere else entirely once the cursor
+        moves across.
+        """
+        screen = QGuiApplication.screenAt(rect.center()) or QGuiApplication.primaryScreen()
         if screen is None:
             return None
         return screen.grabWindow(0, rect.x(), rect.y(), rect.width(), rect.height())
 
-    def screen_bounds(self) -> Tuple[int, int, int, int]:
-        screen = self.screen() or QGuiApplication.primaryScreen()
+    def screen_bounds(self, position=None) -> Tuple[int, int, int, int]:
+        """游標所在螢幕的範圍（沒給座標就用放大鏡自己那一台）。"""
+        screen = None
+        if position is not None:
+            screen = QGuiApplication.screenAt(position)
+        screen = screen or self.screen() or QGuiApplication.primaryScreen()
         if screen is None:
             return (0, 0, 1920, 1080)
         geometry = screen.geometry()
@@ -104,7 +116,7 @@ class MagnifierWidget(BaseWidget):
         try:
             position = self._cursor_provider()
             rect = source_rect((position.x(), position.y()), self.view_size, self.zoom,
-                               self.screen_bounds())
+                               self.screen_bounds(position))
             self.captured = self._grabber(rect)
         except Exception as error:  # pragma: no cover - capture boundary
             front_engine_logger.debug(f"[MagnifierWidget] capture failed: {error!r}")