frontengine 1.0.45__tar.gz → 1.0.46__tar.gz

{frontengine-1.0.45 → frontengine-1.0.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.45
+Version: 1.0.46
 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
@@ -196,6 +196,28 @@ Four things on the **Stream** tab, for playing and for going live:
 
 ---
 
+## Screen-sharing privacy
+
+Your overlays are for you, not for the people you are sharing with. From
+**Settings → Screen-sharing privacy**, FrontEngine can take them out of the
+capture while a meeting app is open:
+
+- **They stay on your own screen.** Only the captured copy is blank — this uses
+  Windows' `WDA_EXCLUDEFROMCAPTURE`, an OS-level flag that conferencing apps and
+  recorders honour.
+- **Masks are the exception.** A distraction mask exists to cover something, so
+  it deliberately stays visible in the capture.
+- **The trigger is your list.** Windows has no dependable "am I being captured"
+  API, so it watches for window titles you name — which also catches a meeting
+  held in a browser tab, where the executable is just the browser.
+
+There is a manual **Hide from capture** button in the control center too.
+
+> This is privacy, not security: it defeats the ordinary capture path, and it
+> never hides anything from the person sitting at the desk. Windows only.
+
+---
+
 ## Screen time, clipboard and layouts
 
 Three things that remember, all of them **off until you switch them on** and

{frontengine-1.0.45 → frontengine-1.0.46}/README.md

@@ -172,6 +172,28 @@ Four things on the **Stream** tab, for playing and for going live:
 
 ---
 
+## Screen-sharing privacy
+
+Your overlays are for you, not for the people you are sharing with. From
+**Settings → Screen-sharing privacy**, FrontEngine can take them out of the
+capture while a meeting app is open:
+
+- **They stay on your own screen.** Only the captured copy is blank — this uses
+  Windows' `WDA_EXCLUDEFROMCAPTURE`, an OS-level flag that conferencing apps and
+  recorders honour.
+- **Masks are the exception.** A distraction mask exists to cover something, so
+  it deliberately stays visible in the capture.
+- **The trigger is your list.** Windows has no dependable "am I being captured"
+  API, so it watches for window titles you name — which also catches a meeting
+  held in a browser tab, where the executable is just the browser.
+
+There is a manual **Hide from capture** button in the control center too.
+
+> This is privacy, not security: it defeats the ordinary capture path, and it
+> never hides anything from the person sitting at the desk. Windows only.
+
+---
+
 ## Screen time, clipboard and layouts
 
 Three things that remember, all of them **off until you switch them on** and

{frontengine-1.0.45 → frontengine-1.0.46}/frontengine/show/base_widget.py

@@ -33,6 +33,12 @@ class BaseWidget(QWidget):
         # 畫質檔位：影響更新頻率上限與算圖縮放（見 utils/power_mode）
         # Quality tier: caps the refresh rate and scales rendering (see utils/power_mode).
         self.quality_tier: str = DEFAULT_TIER
+        # 分享畫面時要不要一起藏起來。遮蔽用的覆蓋層要留在畫面上——
+        # 那正是它存在的理由，藏了就等於沒遮。
+        # Whether this hides along with the others while sharing. A masking
+        # overlay must stay visible in the capture: hiding it would defeat
+        # the only thing it is for.
+        self.keep_in_capture: bool = False
         self._drag_origin = None
         self._geometry_restored = False
 

{frontengine-1.0.45 → frontengine-1.0.46}/frontengine/show/focus_shield/focus_shield_widget.py

@@ -118,6 +118,9 @@ class DistractionMaskWidget(BaseWidget):
             f"[DistractionMaskWidget] Init | region={region}, percent={percent}")
         super().__init__()
         self.opacity = 1.0
+        # 這一層是拿來遮住東西的，分享畫面時必須留在擷取結果裡
+        # This layer exists to cover something, so it stays in the capture.
+        self.keep_in_capture = True
         self.region = region
         self.percent = clamp_percent(percent)
         self.mask_color = QColor(color) if QColor(color).isValid() else QColor("#101010")

frontengine-1.0.46/frontengine/ui/dialog/screen_privacy_dialog.py

@@ -0,0 +1,98 @@
+"""
+螢幕分享隱私設定：偵測到會議程式時，自動把覆蓋層藏出擷取畫面。
+
+Windows 沒有可靠的「我正在被擷取嗎」API，所以判斷依據是使用者自己列出的
+會議程式有沒有開著視窗。這是刻意的：與其猜錯，不如讓使用者說了算。
+
+Screen-sharing privacy: hide the overlays from the capture when a meeting app
+turns up.
+
+Windows offers no dependable "am I being captured" API, so the trigger is
+whether one of the apps the user listed has a window open. That is deliberate -
+better their list than our guess.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from PySide6.QtWidgets import (
+    QCheckBox, QDialog, QDialogButtonBox, QGridLayout, QLabel, QLineEdit, QWidget,
+)
+
+from frontengine.user_setting.user_setting_file import user_setting_dict, write_user_setting
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+from frontengine.utils.multi_language.language_wrapper import language_wrapper
+from frontengine.utils.screen_privacy import capture_affinity
+from frontengine.utils.screen_privacy.share_watch import DEFAULT_SHARING_APPS
+from frontengine.utils.smart_pause.pause_rules import parse_app_list
+
+SETTING_KEY = "screen_share_privacy"
+DEFAULT_SETTINGS: Dict[str, Any] = {"enabled": False, "apps": list(DEFAULT_SHARING_APPS)}
+
+
+def _t(key: str, fallback: str) -> str:
+    return language_wrapper.language_word_dict.get(key, fallback)
+
+
+def current_settings() -> Dict[str, Any]:
+    """目前的分享隱私設定（缺項目補預設值）。"""
+    stored = user_setting_dict.get(SETTING_KEY)
+    settings = dict(DEFAULT_SETTINGS)
+    if isinstance(stored, dict):
+        settings.update({key: stored[key] for key in DEFAULT_SETTINGS if key in stored})
+    settings["apps"] = parse_app_list(settings.get("apps")) or list(DEFAULT_SHARING_APPS)
+    return settings
+
+
+class ScreenPrivacyDialog(QDialog):
+    """設定哪些程式算是「正在分享」，以及要不要自動隱藏。"""
+
+    def __init__(self, parent: Optional[QWidget] = None) -> None:
+        front_engine_logger.info("[ScreenPrivacyDialog] Init")
+        super().__init__(parent)
+        self.setWindowTitle(_t("screen_privacy_title", "Screen-sharing privacy"))
+        settings = current_settings()
+
+        self.enable_checkbox = QCheckBox(
+            _t("screen_privacy_enable", "Hide overlays while one of these apps is open"))
+        self.enable_checkbox.setChecked(bool(settings.get("enabled")))
+        self.apps_label = QLabel(_t("screen_privacy_apps_label", "Meeting and capture apps:"))
+        self.apps_edit = QLineEdit(", ".join(settings.get("apps", [])))
+        self.apps_edit.setPlaceholderText("zoom, teams, discord")
+        self.hint_label = QLabel(
+            _t("screen_privacy_hint",
+               "Matched against window titles, so a meeting held in a browser tab is caught "
+               "too. Your overlays stay on your own screen - only the capture is blank. "
+               "Masks stay visible, since covering something is what they are for.")
+            if capture_affinity.available() else
+            _t("screen_privacy_unsupported",
+               "Hiding overlays from screen capture is Windows only."))
+        self.hint_label.setWordWrap(True)
+
+        self.button_box = QDialogButtonBox(
+            QDialogButtonBox.StandardButton.Ok | QDialogButtonBox.StandardButton.Cancel)
+        self.button_box.accepted.connect(self.accept)
+        self.button_box.rejected.connect(self.reject)
+
+        layout = QGridLayout(self)
+        layout.addWidget(self.enable_checkbox, 0, 0, 1, 2)
+        layout.addWidget(self.apps_label, 1, 0, 1, 2)
+        layout.addWidget(self.apps_edit, 2, 0, 1, 2)
+        layout.addWidget(self.hint_label, 3, 0, 1, 2)
+        layout.addWidget(self.button_box, 4, 0, 1, 2)
+        for widget in (self.enable_checkbox, self.apps_edit):
+            widget.setEnabled(capture_affinity.available())
+
+    def settings(self) -> Dict[str, Any]:
+        """對話框上目前的設定。"""
+        return {
+            "enabled": self.enable_checkbox.isChecked(),
+            "apps": parse_app_list(self.apps_edit.text()) or list(DEFAULT_SHARING_APPS),
+        }
+
+    def accept(self) -> None:
+        settings = self.settings()
+        user_setting_dict[SETTING_KEY] = settings
+        write_user_setting()
+        front_engine_logger.info(f"[ScreenPrivacyDialog] saved | {settings}")
+        super().accept()

{frontengine-1.0.45 → frontengine-1.0.46}/frontengine/ui/main_ui.py

@@ -49,7 +49,9 @@ from frontengine.utils.logging.loggin_instance import front_engine_logger
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
 from frontengine.utils.plugins.plugin_loader import load_plugins
 from frontengine.utils.preset_schedule.preset_schedule_service import PresetScheduleService
+from frontengine.ui.dialog.screen_privacy_dialog import current_settings as current_privacy_settings
 from frontengine.ui.dialog.smart_pause_dialog import current_rules
+from frontengine.utils.screen_privacy.share_watch import ShareWatchService
 from frontengine.utils.app_profile.app_profile_service import AppProfileService
 from frontengine.utils.clipboard.clipboard_history import DEFAULT_LIMIT, ClipboardHistory
 from frontengine.utils.clipboard.clipboard_watcher import ClipboardWatcher
@@ -209,6 +211,12 @@ class FrontEngineMainUI(QMainWindow):
         )
         self.app_profile_service.start()
 
+        # 分享畫面時把覆蓋層藏出擷取結果（自己仍看得到）
+        # Hide the overlays from the capture while sharing; they stay on screen here.
+        self.share_watch_service = ShareWatchService(config_provider=current_privacy_settings)
+        self.share_watch_service.sharing_changed.connect(self._on_sharing_changed)
+        self.share_watch_service.start()
+
         # 使用時間統計：預設關閉，只寫本機檔案，使用者可隨時清除
         # Usage tracking: off by default, local file only, clearable at any time.
         self.usage_tracker = UsageTracker(JsonRepository(Path(getcwd()) / USAGE_FILE))
@@ -460,6 +468,22 @@ class FrontEngineMainUI(QMainWindow):
             self.control_center_ui.show_all()
             self._smart_pause_hid = False
 
+    def _on_sharing_changed(self, sharing: bool, match: str) -> None:
+        """
+        偵測到會議程式開著／關掉時，自動把覆蓋層藏出擷取結果或放回去。
+        遮蔽用的覆蓋層不受影響——它們本來就是要被看到的。
+        Hide the overlays from the capture when a meeting app appears, and put
+        them back when it goes. Masking overlays are left alone: being seen is
+        the whole point of them.
+        """
+        front_engine_logger.info(
+            f"[MainUI] screen sharing={sharing}" + (f" | {match}" if match else ""))
+        self.control_center_ui.set_hide_from_capture(sharing)
+        if sharing:
+            self._last_toast = show_toast(
+                language_wrapper.language_word_dict.get(
+                    "screen_privacy_toast", "Overlays hidden from screen capture"))
+
     def _show_reminder(self, label: str) -> None:
         """提醒到期：在畫面上方顯示一張會自己消失的提示卡。"""
         front_engine_logger.info(f"[MainUI] reminder | {label}")
@@ -526,6 +550,8 @@ class FrontEngineMainUI(QMainWindow):
             self.tools_setting_ui.stop_camera()
         if getattr(self, "stream_setting_ui", None) is not None:
             self.stream_setting_ui.soundboard.stop_all()
+        if getattr(self, "share_watch_service", None) is not None:
+            self.share_watch_service.stop()
         if getattr(self, "reminder_service", None) is not None:
             self.reminder_service.stop()
         if getattr(self, "app_profile_service", None) is not None:

{frontengine-1.0.45 → frontengine-1.0.46}/frontengine/ui/menu/settings_menu.py

@@ -10,6 +10,7 @@ from frontengine.ui.dialog.app_profile_dialog import AppProfileDialog
 from frontengine.ui.dialog.clipboard_dialog import ClipboardDialog
 from frontengine.ui.dialog.hotkey_settings_dialog import HotkeySettingsDialog
 from frontengine.ui.dialog.reminder_dialog import ReminderDialog
+from frontengine.ui.dialog.screen_privacy_dialog import ScreenPrivacyDialog
 from frontengine.ui.dialog.smart_pause_dialog import SmartPauseDialog
 from frontengine.ui.dialog.usage_report_dialog import UsageReportDialog
 from frontengine.user_setting.user_setting_file import (
@@ -87,6 +88,12 @@ def build_settings_menu(ui: "FrontEngineMainUI") -> None:
     menu.addAction(reminder_action)
     ui.reminder_action = reminder_action
 
+    privacy_action = QAction(
+        _t("settings_menu_screen_privacy", "Screen-sharing privacy..."), menu)
+    privacy_action.triggered.connect(lambda: _open_dialog(ui, ScreenPrivacyDialog))
+    menu.addAction(privacy_action)
+    ui.screen_privacy_action = privacy_action
+
     usage_action = QAction(_t("settings_menu_usage", "Screen time..."), menu)
     usage_action.triggered.connect(lambda: _open_usage_dialog(ui))
     menu.addAction(usage_action)

{frontengine-1.0.45 → frontengine-1.0.46}/frontengine/ui/page/control_center/control_center_ui.py

@@ -16,6 +16,7 @@ from frontengine.ui.page.web.web_setting_ui import WEBSettingUI
 from frontengine.user_setting.user_setting_file import clear_overlay_geometry
 from frontengine.utils.logging.loggin_instance import front_engine_logger
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
+from frontengine.utils.screen_privacy import capture_affinity
 from frontengine.utils.power_mode.power_mode import (
     TIER_BALANCED, TIER_HIGH, TIER_SAVER, normalize_tier,
 )
@@ -94,6 +95,10 @@ class ControlCenterUI(QWidget):
         self._extra_overlay_sources: list = []
         self.low_power_button = self._create_button(
             "control_center_low_power_on", self.toggle_low_power)
+        self._hidden_from_capture = False
+        self.capture_button = self._create_button(
+            "control_center_hide_from_capture", self.toggle_hide_from_capture)
+        self.capture_button.setEnabled(capture_affinity.available())
         self.clear_all_button = self._create_button("control_center_close_all", self.clear_all)
 
         # 畫質檔位：比省電模式更細，一次套用到所有覆蓋層
@@ -135,8 +140,9 @@ class ControlCenterUI(QWidget):
         self.grid_layout.addWidget(self.low_power_button, 13, 0)
         self.grid_layout.addWidget(self.quality_label, 14, 0)
         self.grid_layout.addWidget(self.quality_combobox, 15, 0)
-        self.grid_layout.addWidget(self.clear_all_button, 16, 0)
-        self.grid_layout.addWidget(self.log_panel_scroll_area, 0, 1, 17, 1)  # rowSpan covers every button
+        self.grid_layout.addWidget(self.capture_button, 16, 0)
+        self.grid_layout.addWidget(self.clear_all_button, 17, 0)
+        self.grid_layout.addWidget(self.log_panel_scroll_area, 0, 1, 18, 1)  # rowSpan covers every button
         self.setLayout(self.grid_layout)
 
         # Redirect
@@ -353,6 +359,43 @@ class ControlCenterUI(QWidget):
             )
         )
 
+    def set_hide_from_capture(self, hidden: bool) -> int:
+        """
+        分享畫面時把覆蓋層藏起來（自己看得到、對方看不到）。標了
+        keep_in_capture 的覆蓋層不會被藏——遮蔽層本來就是要被看到的。
+        Hide the overlays from screen capture: still visible here, blank for the
+        people you are sharing with. Overlays marked keep_in_capture are left
+        alone, since a mask is meant to be seen.
+        """
+        self._hidden_from_capture = bool(hidden)
+        applied = 0
+
+        def apply(widget) -> None:
+            nonlocal applied
+            if getattr(widget, "keep_in_capture", False):
+                capture_affinity.apply_to_widget(widget, False)
+                return
+            if capture_affinity.apply_to_widget(widget, self._hidden_from_capture):
+                applied += 1
+
+        self._for_each_overlay(apply)
+        front_engine_logger.info(
+            f"ControlCenterUI set_hide_from_capture | hidden={hidden}, applied={applied}")
+        self.capture_button.setText(
+            language_wrapper.language_word_dict.get(
+                "control_center_show_in_capture" if self._hidden_from_capture
+                else "control_center_hide_from_capture",
+                "Show in capture" if self._hidden_from_capture else "Hide from capture"))
+        return applied
+
+    def toggle_hide_from_capture(self) -> None:
+        """切換分享時是否隱藏覆蓋層。"""
+        self.set_hide_from_capture(not self._hidden_from_capture)
+
+    @property
+    def hidden_from_capture(self) -> bool:
+        return self._hidden_from_capture
+
     def toggle_low_power(self) -> None:
         """切換省電模式 / Toggle low-power mode."""
         self.set_low_power(not getattr(self, "_low_power", False))

{frontengine-1.0.45 → frontengine-1.0.46}/frontengine/user_setting/user_setting_file.py

@@ -54,6 +54,9 @@ user_setting_dict: Dict[str, Any] = {
     # Sticky note contents and positions, and whether to reopen them on launch.
     "sticky_notes": [],
     "sticky_notes_restore": False,
+    # 分享畫面時自動把覆蓋層藏出擷取結果（預設關閉）
+    # Hide overlays from the capture while sharing; off by default.
+    "screen_share_privacy": {"enabled": False, "apps": []},
     # 使用時間統計（只寫本機檔案、預設關閉）
     # Usage tracking: local file only, off by default.
     "usage_tracking": False,

{frontengine-1.0.45 → frontengine-1.0.46}/frontengine/utils/multi_language/english.py

@@ -542,4 +542,13 @@ english_word_dict = {
     "stream_obs_record": 'Toggle recording',
     "stream_obs_stream": 'Toggle streaming',
     "stream_hint": 'The crosshair is only drawn on top - no game is modified. OBS control uses its own WebSocket; the password is kept in your local settings.',
+    "control_center_hide_from_capture": 'Hide from capture',
+    "control_center_show_in_capture": 'Show in capture',
+    "settings_menu_screen_privacy": 'Screen-sharing privacy...',
+    "screen_privacy_title": 'Screen-sharing privacy',
+    "screen_privacy_enable": 'Hide overlays while one of these apps is open',
+    "screen_privacy_apps_label": 'Meeting and capture apps:',
+    "screen_privacy_hint": 'Matched against window titles, so a meeting held in a browser tab is caught too. Your overlays stay on your own screen - only the capture is blank. Masks stay visible, since covering something is what they are for.',
+    "screen_privacy_unsupported": 'Hiding overlays from screen capture is Windows only.',
+    "screen_privacy_toast": 'Overlays hidden from screen capture',
 }

{frontengine-1.0.45 → frontengine-1.0.46}/frontengine/utils/multi_language/traditional_chinese.py

@@ -541,4 +541,13 @@ traditional_chinese_word_dict = {
     "stream_obs_record": '切換錄影',
     "stream_obs_stream": '切換直播',
     "stream_hint": '準星只是疊在畫面上的一層，不會更動任何遊戲。OBS 控制走它自己的 WebSocket，密碼只留在本機設定檔裡。',
+    "control_center_hide_from_capture": '分享時隱藏',
+    "control_center_show_in_capture": '分享時顯示',
+    "settings_menu_screen_privacy": '螢幕分享隱私…',
+    "screen_privacy_title": '螢幕分享隱私',
+    "screen_privacy_enable": '這些程式開著時，把覆蓋層藏出擷取畫面',
+    "screen_privacy_apps_label": '會議與擷取程式：',
+    "screen_privacy_hint": '比對的是視窗標題，所以在瀏覽器分頁裡開的會議也抓得到。覆蓋層仍會顯示在你自己的螢幕上，只有擷取畫面那一份是空的。遮蔽層不會被藏起來——遮住東西正是它存在的理由。',
+    "screen_privacy_unsupported": '把覆蓋層藏出螢幕擷取僅支援 Windows。',
+    "screen_privacy_toast": '已把覆蓋層藏出螢幕擷取',
 }

frontengine-1.0.46/frontengine/utils/screen_privacy/capture_affinity.py

@@ -0,0 +1,120 @@
+"""
+把視窗排除在螢幕擷取之外：分享畫面時，自己看得到覆蓋層，對方看不到。
+
+用的是 Win32 的 `SetWindowDisplayAffinity(WDA_EXCLUDEFROMCAPTURE)`。這是作業系統
+層級的旗標——會議軟體、錄影軟體、螢幕擷取 API 拿到的畫面裡那塊會是空的，
+而本機螢幕上照常顯示。僅 Windows 10 2004 以後有效，其他平台一律回報做不到。
+
+**這是「隱私」不是「保全」**：它擋的是正常的擷取管道，不是防止有心人用其他
+方式取得畫面，也不會讓視窗對使用者自己隱形。
+
+Keep a window out of screen captures: you still see your overlays while the
+people you are sharing with do not.
+
+This is Win32's `SetWindowDisplayAffinity(WDA_EXCLUDEFROMCAPTURE)` - an
+OS-level flag, so conferencing apps, recorders and capture APIs all receive
+blank pixels there while the local display is unchanged. Windows 10 2004 and
+later; everywhere else it reports that it cannot be done.
+
+**This is privacy, not security**: it defeats the ordinary capture path, not a
+determined attacker, and it never hides the window from the person at the desk.
+"""
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+# WDA_NONE：正常擷取；WDA_EXCLUDEFROMCAPTURE：擷取時整片留白
+# WDA_NONE captures normally; WDA_EXCLUDEFROMCAPTURE comes out blank.
+WDA_NONE = 0x00000000
+WDA_EXCLUDEFROMCAPTURE = 0x00000011
+
+
+def available() -> bool:
+    """這個平台能不能控制擷取可見性。"""
+    return sys.platform == "win32"
+
+
+def _user32():
+    """拿到宣告好 argtypes 的 user32；非 Windows 回傳 None。"""
+    if not available():
+        return None
+    import ctypes
+    from ctypes import wintypes
+
+    user32 = ctypes.windll.user32
+    user32.SetWindowDisplayAffinity.argtypes = [wintypes.HWND, wintypes.DWORD]
+    user32.SetWindowDisplayAffinity.restype = wintypes.BOOL
+    user32.GetWindowDisplayAffinity.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.DWORD)]
+    user32.GetWindowDisplayAffinity.restype = wintypes.BOOL
+    return user32
+
+
+def set_excluded_from_capture(handle: int, excluded: bool) -> bool:
+    """
+    設定某個視窗要不要被排除在擷取之外；成功回傳 True。
+    Set whether a window is excluded from capture; True when it took effect.
+    """
+    user32 = _user32()
+    if user32 is None or not handle:
+        return False
+    try:
+        from ctypes import wintypes
+
+        affinity = WDA_EXCLUDEFROMCAPTURE if excluded else WDA_NONE
+        result = user32.SetWindowDisplayAffinity(wintypes.HWND(int(handle)), affinity)
+        front_engine_logger.debug(
+            f"[CaptureAffinity] {handle} excluded={excluded} ok={bool(result)}")
+        return bool(result)
+    except Exception as error:  # pragma: no cover - Win32 boundary
+        front_engine_logger.warning(f"[CaptureAffinity] failed: {error!r}")
+        return False
+
+
+def is_excluded_from_capture(handle: int) -> Optional[bool]:
+    """某個視窗目前是不是被排除在擷取之外；問不到回傳 None。"""
+    user32 = _user32()
+    if user32 is None or not handle:
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        affinity = wintypes.DWORD()
+        if not user32.GetWindowDisplayAffinity(wintypes.HWND(int(handle)),
+                                               ctypes.byref(affinity)):
+            return None
+        return affinity.value == WDA_EXCLUDEFROMCAPTURE
+    except Exception as error:  # pragma: no cover - Win32 boundary
+        front_engine_logger.debug(f"[CaptureAffinity] read failed: {error!r}")
+        return None
+
+
+def apply_to_widget(widget, excluded: bool) -> bool:
+    """
+    對一個 Qt widget 套用擷取可見性。視窗還沒建立原生 handle 時回傳 False，
+    呼叫端可以等 show() 之後再試一次。
+    Apply capture visibility to a Qt widget. False when it has no native handle
+    yet, so the caller can try again after show().
+    """
+    if widget is None:
+        return False
+    try:
+        handle = int(widget.winId())
+    except (RuntimeError, ValueError):  # pragma: no cover - widget torn down
+        return False
+    return set_excluded_from_capture(handle, excluded)
+
+
+def apply_to_widgets(widgets, excluded: bool) -> int:
+    """對一批 widget 套用，回傳成功的數量。"""
+    applied = 0
+    for widget in list(widgets or ()):
+        try:
+            if apply_to_widget(widget, excluded):
+                applied += 1
+        except RuntimeError:  # pragma: no cover - widget closed mid-loop
+            continue
+    return applied

frontengine-1.0.46/frontengine/utils/screen_privacy/share_watch.py

@@ -0,0 +1,128 @@
+"""
+偵測「可能正在分享畫面」：看使用者指定的會議程式在不在。
+
+Windows 沒有可靠的「我現在被擷取了嗎」API，所以這裡用的是誠實的近似：
+使用者自己列出會議軟體（Zoom、Teams、Discord…），只要那些程式有開著視窗，
+就當作可能在分享。這是刻意選擇的做法——與其猜錯，不如讓使用者說了算。
+
+Spot "probably sharing the screen" by watching for the meeting apps the user
+named.
+
+Windows has no dependable "am I being captured" API, so this is an honest
+approximation: the user lists their conferencing apps, and any of them having a
+window open counts as possibly sharing. That is deliberate - better to let the
+user decide than to guess wrong.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from PySide6.QtCore import QObject, QTimer, Signal
+
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+from frontengine.utils.smart_pause.pause_rules import normalize_app_name, parse_app_list
+from frontengine.utils.window_pin.window_pin import list_windows
+
+# 常見的會議／串流程式，當作預設值；使用者可以自己改
+# The usual conferencing and streaming apps, as a starting point the user edits.
+DEFAULT_SHARING_APPS = ("zoom", "teams", "ms-teams", "discord", "obs64", "obs",
+                        "slack", "webex", "gotomeeting")
+DEFAULT_INTERVAL_MS = 3000
+
+
+def running_app_names(lister: Optional[Callable[[], List]] = None) -> List[str]:
+    """
+    目前有視窗的程式名稱（正規化過）。用視窗列舉而不是列舉所有程序：
+    看得見的視窗才可能被分享，也不需要更高的權限。
+    The normalized names of apps that currently have a window. Window
+    enumeration rather than a full process list: only visible windows can be
+    shared, and it needs no extra privileges.
+    """
+    names = []
+    for _handle, title in (lister or list_windows)() or []:
+        name = normalize_app_name(title)
+        if name and name not in names:
+            names.append(name)
+    return names
+
+
+def sharing_app_running(watched: Any, window_titles: List[str]) -> Optional[str]:
+    """
+    有沒有被盯著的程式開著視窗。比對是「視窗標題裡含有那個名字」——會議軟體
+    的標題通常帶著自己的名字（例如 "Zoom Meeting"），比對執行檔名反而抓不到
+    瀏覽器裡開的會議。回傳第一個命中的名字，沒有就 None。
+    Whether one of the watched apps has a window. Matching is "the title
+    contains the name", because meeting windows usually carry their app's name
+    ("Zoom Meeting") while an executable-name match would miss a meeting held
+    in a browser tab. Returns the first hit, or None.
+    """
+    wanted = parse_app_list(watched) or list(DEFAULT_SHARING_APPS)
+    haystack = [title.lower() for title in window_titles]
+    for name in wanted:
+        if any(name in title for title in haystack):
+            return name
+    return None
+
+
+class ShareWatchService(QObject):
+    """
+    定時檢查有沒有會議程式開著，狀態改變時發出訊號。視窗來源與設定都可注入。
+    Poll for a conferencing app and signal when that changes. Both the window
+    source and the configuration are injectable.
+    """
+
+    sharing_changed = Signal(bool, str)  # (可能在分享, 命中的程式名稱)
+
+    def __init__(self, config_provider: Optional[Callable[[], Dict[str, Any]]] = None,
+                 window_provider: Optional[Callable[[], List]] = None,
+                 interval_ms: int = DEFAULT_INTERVAL_MS,
+                 parent: Optional[QObject] = None) -> None:
+        super().__init__(parent)
+        self._config_provider = config_provider or (lambda: {})
+        self._window_provider = window_provider or list_windows
+        self._sharing = False
+        self._match = ""
+        self._timer = QTimer(self)
+        self._timer.setInterval(max(1000, int(interval_ms)))
+        self._timer.timeout.connect(self.poll_once)
+
+    @property
+    def sharing(self) -> bool:
+        return self._sharing
+
+    @property
+    def match(self) -> str:
+        """目前是哪個程式讓它判斷成「在分享」。"""
+        return self._match
+
+    def start(self) -> None:
+        front_engine_logger.info("[ShareWatch] start")
+        self._timer.start()
+
+    def stop(self) -> None:
+        front_engine_logger.info("[ShareWatch] stop")
+        self._timer.stop()
+
+    def poll_once(self) -> None:
+        """檢查一次（測試會直接呼叫）。"""
+        try:
+            config = self._config_provider() or {}
+            if not config.get("enabled", False):
+                self._update(False, "")
+                return
+            titles = [str(title) for _handle, title in (self._window_provider() or [])]
+            match = sharing_app_running(config.get("apps"), titles)
+        except Exception as error:  # pragma: no cover - defensive boundary
+            front_engine_logger.warning(f"[ShareWatch] poll error: {error!r}")
+            return
+        self._update(match is not None, match or "")
+
+    def _update(self, sharing: bool, match: str) -> None:
+        if sharing == self._sharing:
+            self._match = match
+            return
+        self._sharing = sharing
+        self._match = match
+        front_engine_logger.info(
+            f"[ShareWatch] sharing={sharing}" + (f" | {match}" if match else ""))
+        self.sharing_changed.emit(sharing, match)