dsh-notify-me 1.10.4 → 1.10.5

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to **dsh-notify-me** are documented here.
 
+## [1.10.5] — 2026-10-21
+
+### 修复
+
+- **桌面端窗口被遮住时「回复完成」不提醒**：本插件判断「你离开了」只看 `document.hidden` / `visibilityState`，而桌面壳里把 DSH 窗口切到别的应用后面、或被别的窗口盖住时，页面依然是 `visible` —— 只有最小化或整窗被遮挡才会变成 `hidden`。于是「只在后台提醒」的回复完成提醒在窗口只是被盖住时被静默丢弃（1.10.5 之前只在真正最小化时才响）。现在把窗口焦点也算进「离开」：页面失焦即视为后台，失焦瞬间同样补发此前因为「就在你眼前」而被压下的审批提醒；窗口回到前台后照常安静。设置页三个相关开关的文案同步改为「窗口在前台时也提醒」，说明里点明「切走 / 被遮挡 / 最小化」都算后台。
+
+### 测试
+
+- 冒烟新增 `awayWithoutHiding` 用例：焦点在时回复完成静默、失焦后同一页发出提醒、回焦再次静默、`visibilityState` 全程保持 `visible`、失焦时补发被压下的审批提醒。
+
 ## [1.10.4] — 2026-10-21
 
 ### 新增

package/README.en.md

@@ -75,7 +75,7 @@ The Electron application manages the `desktop` profile. Do not change the Web co
 
 1. Click once in the DSH page and allow notifications when prompted. If you previously declined, allow them in the browser's site settings. The operating system must also allow notifications from the browser / DSH Desktop.
 2. Open **Settings → Notify me**. Confirm that the section and plugin version at its foot appear, and leave the master switch, the alert type on system notifications, and sound enabled.
-3. Click **Test "reply finished"** on the settings page. A test notification should appear and sound according to your cue settings. This local test does not forward to external endpoints and ignores the "while the page is open" toggle.
+3. Click **Test "reply finished"** on the settings page. A test notification should appear and sound according to your cue settings. This local test does not forward to external endpoints and ignores the "while the window is in front" toggle.
 
 Web users can also test approval buttons. On Desktop the shell cannot register a Service Worker, so this test draws an in-page card with Approve / Reject in the window corner (since 1.10.4; earlier versions sent a plain notification).
 
@@ -110,7 +110,7 @@ dsh-notify-me decouples **supervision** from **sitting in front of the screen**:
 
 **Input needed** covers approval requests, plan review, and questions (`ask_user_question`). Approvals carry Approve / Reject: on Web as a system notification with buttons, on Desktop (which cannot register a Service Worker) as a card drawn in the window corner.
 
-**Reply finished** also covers background sessions. A finished but unread session keeps the `✅ Reply finished ·` title marker until opened. Title markers are independent of the "while the page is open" toggles.
+**Reply finished** also covers background sessions. A finished but unread session keeps the `✅ Reply finished ·` title marker until opened. Title markers are independent of the "while the window is in front" toggles.
 
 > **Background** subagent child sessions are **not** alerted about by default: DSH lists each of them as its own session, but they are steps inside the parent conversation's turn, so an alert for them is only noise. The subagent session you have open is not part of this and alerts as usual. Settings → "Ignore subagent sessions" turns the mute off.
 
@@ -143,9 +143,9 @@ The overlay only knows which screen the window is on, not which screen you are l
 
 ### When to alert
 
-- **Also alert "needs you" while the page is open** (on): turn it off to hear only from the background;
-- **Stay quiet for the conversation on screen** (on): a wait belonging to the conversation you are looking at keeps only the tab marker so the approval card stays readable; backgrounding restores alerts;
-- **Also alert "reply finished" while the page is open** (off): by default only background finishes alert;
+- **Also alert "needs you" while the window is in front** (on): turn it off to hear only once the window goes to the background — another app focused, the window covered, or minimized all count;
+- **Stay quiet for the conversation on screen** (on): a wait belonging to the conversation you are looking at keeps only the tab marker so the approval card stays readable; moving the window to the background restores alerts;
+- **Also alert "reply finished" while the window is in front** (off): by default only background finishes alert (a covered Desktop window counts as background since 1.10.5, not only a minimized one);
 - **Ignore subagent sessions** (on): skip background sessions spawned by a subagent — the parent conversation covers them; the one you have open still alerts;
 - **Click a toast to open that conversation** (on): the click switches to the conversation that raised it; in a browser it also brings the window forward, while on the Desktop shell it is flaky — sometimes the window comes forward, sometimes only the conversation switches (see [How the Desktop window gets raised](#how-the-desktop-window-gets-raised)); with several tabs open only one is raised, and off means a click does nothing.
 

package/README.md

@@ -75,7 +75,7 @@ dsh plugin --profile web add dsh-notify-me
 
 1. 在 DSH 页面上点击一次，按提示允许通知；若此前拒绝过，在浏览器站点设置中允许通知。操作系统也需要允许对应浏览器 / DSH Desktop 显示通知。
 2. 打开 **设置 → 通知提醒**，确认出现该分区及底部插件版本号，保持「启用提醒」「提示音」开启，通知类型先留「系统通知」。
-3. 点击设置页的「测试『回复完成』」按钮：应出现一条测试通知，并按当前音效设置播放声音。这个本地测试不会转发到外部通知端点，也不受「页面打开时也提醒」开关限制。
+3. 点击设置页的「测试『回复完成』」按钮：应出现一条测试通知，并按当前音效设置播放声音。这个本地测试不会转发到外部通知端点，也不受「窗口在前台时也提醒」开关限制。
 
 Web 用户可再测试审批按钮。桌面端拿不到 Service Worker，这条测试会在窗口角落画一张带「同意 / 拒绝」的卡片（1.10.4 起；之前的版本这里只发普通通知）。
 
@@ -106,7 +106,7 @@ dsh-notify-me 把「监督」和「守在屏幕前」解耦：只在真的出现
 
 **需要你操作**包括审批请求、方案待确认（plan review）和提问（`ask_user_question`）。审批带「同意 / 拒绝」：Web 走带按钮的系统通知，桌面端（注册不了 Service Worker）改画在窗口角落的卡片上。
 
-**回复完成**也覆盖后台会话；完成但还没看时，标题带 `✅ 回复完成 ·` 标记，打开对应会话即撤。标题标记不受「页面打开时也提醒」开关限制。
+**回复完成**也覆盖后台会话；完成但还没看时，标题带 `✅ 回复完成 ·` 标记，打开对应会话即撤。标题标记不受「窗口在前台时也提醒」开关限制。
 
 > **后台**子代理（subagent）子会话的等待与完成默认**不提醒**：DSH 把每个子代理子会话列成独立会话，但它们是所属主对话那一轮里的步骤，提醒只会是噪音。你当前打开的那个子代理会话不算在内，照常提醒。设置页「子代理会话不提醒」可关掉这个静音。
 
@@ -139,9 +139,9 @@ Windows 的系统通知横幅固定画在主屏上，系统没有设置项、浏
 
 ### 什么时候提醒
 
-- **页面打开时也提醒「需要你」**（默认开）：页面在最前也提醒；关掉后只有切到后台才提醒；
-- **当前对话不弹通知**（默认开）：等待就发生在你正看着的对话里时只留标签页标记，免得挡住审批卡片；切到后台后照常提醒，若你已处理掉就作废；
-- **页面打开时也提醒「回复完成」**（默认关）：默认只在切到后台时提醒，避免打扰；
+- **窗口在前台时也提醒「需要你」**（默认开）：窗口在前台也提醒；关掉后只有窗口转到后台才提醒——切到别的应用、被别的窗口遮住、最小化都算后台；
+- **当前对话不弹通知**（默认开）：等待就发生在你正看着的对话里时只留标签页标记，免得挡住审批卡片；窗口转到后台后照常提醒，若你已处理掉就作废；
+- **窗口在前台时也提醒「回复完成」**（默认关）：默认只在窗口转到后台时提醒，避免打扰（桌面端窗口被遮住也算后台，1.10.5 起不再要求最小化）；
 - **子代理会话不提醒**（默认开）：跳过后台子代理（subagent）会话——它们是主对话那一轮的步骤，完成由主对话自己的提醒覆盖；你当前打开的那个子代理会话照常提醒；
 - **点击通知回到对应对话**（默认开）：点通知切到提醒所属的对话；浏览器里同时把窗口带到前台；桌面端不稳定——有时窗口会上前，有时只切对话（见[桌面端怎么抬窗的](#桌面端怎么抬窗的)）；多个标签页同时开着时只调起一个（优先当前可见的那个）；关掉后点通知不做任何事。
 

package/lib/client.js

@@ -1392,6 +1392,25 @@
 
     function hidden() { return document.hidden || document.visibilityState === "hidden"; }
 
+    // "Background" is not the same as "hidden": a desktop window sitting behind
+    // another app, or a browser tab on a second monitor, still reports itself as
+    // visible. Only a minimised or fully occluded window flips document.hidden,
+    // so the reminders that are meant to reach a user who walked away stayed
+    // silent whenever the window was merely covered. Window focus is the missing
+    // half of the signal: an unfocused page counts as away.
+    var pageFocused = true;
+    try {
+      if (typeof document.hasFocus === "function") pageFocused = document.hasFocus() !== false;
+    } catch (e) {}
+    function onPageFocus() { pageFocused = true; }
+    function onPageBlur() {
+      pageFocused = false;
+      // Walking away is what re-arms the waits kept quiet because they belonged
+      // to the conversation on screen; a blur alone never fires visibilitychange.
+      try { flushQuieted(); } catch (e) {}
+    }
+    function away() { return hidden() || !pageFocused; }
+
     // Deliver one alert regardless of visibility rules (used by the test
     // buttons); respects the master switch and permission state. The title
     // marker is NOT touched here — its ownership belongs to the watchers
@@ -1417,13 +1436,13 @@
     }
     function fire(kind, title, body, isCurrent, sessionId, quick) {
       if (!config.enabled) return false;
-      if (kind === "attention" && config.attentionHiddenOnly && !hidden()) return false;
+      if (kind === "attention" && config.attentionHiddenOnly && !away()) return false;
       // The wait belongs to the conversation the user is looking at right now:
       // the approval card is already on screen, so a toast would only cover the
       // thing it is asking about. The caller keeps the tab marker, and
       // flushQuieted() re-delivers the alert the moment the page is backgrounded.
       if (kind === "attention" && quietedByVisibleSession(isCurrent)) return false;
-      if (kind === "done" && config.doneHiddenOnly && !hidden()) return false;
+      if (kind === "done" && config.doneHiddenOnly && !away()) return false;
       deliver(kind, title, body, sessionId, quick);
       // The alert reached the user locally (or would have, had the tab a
       // voice): mirror the same copy to the outside world. Fire-and-forget —
@@ -1435,7 +1454,7 @@
     // session already on screen. Kept separate from fire() so the caller can
     // queue exactly this case and nothing else.
     function quietedByVisibleSession(isCurrent) {
-      return !!(isCurrent && config.currentHiddenOnly && !hidden());
+      return !!(isCurrent && config.currentHiddenOnly && !away());
     }
     // Queued copies of the alerts that rule suppressed. Delivered by key so a
     // wait that got answered while the user was still on the page never fires.
@@ -1443,7 +1462,7 @@
       if (key && copy) quietedAttention[key] = copy;
     }
     function flushQuieted() {
-      if (!config.enabled || !hidden()) return;
+      if (!config.enabled || !away()) return;
       var keys = Object.keys(quietedAttention);
       for (var i = 0; i < keys.length; i++) {
         var copy = quietedAttention[keys[i]];
@@ -2047,7 +2066,7 @@
       });
     } catch (e) {}
     // keep in sync with package.json "version" on every release
-    api.version = "1.10.4";
+    api.version = "1.10.5";
     api.setConfig = function (patch) { return setConfigLocal(patch); };
     api.resetConfig = function () {
       try {
@@ -2149,6 +2168,8 @@
         actionKeys: Object.keys(pendingActions),
         permission: ("Notification" in window) ? Notification.permission : "n/a",
         visibility: hidden() ? "hidden" : "visible",
+        focused: pageFocused,
+        away: away(),
         uiSession: uiPending ? "bound" : "unbound",
         uiSessionNote: uiBindNote,
         uiSessionSource: uiSource,
@@ -2249,12 +2270,12 @@
       externalCountFailed: "失败 ",
       externalNoTargets: "先添加至少一个推送目标。",
       externalOffHint: "先打开「转发外部通知」。",
-      attentionVisible: "页面打开时也提醒「需要你」",
-      attentionVisibleHint: "页面在最前也提醒。关掉后只有切到后台才提醒。",
+      attentionVisible: "窗口在前台时也提醒「需要你」",
+      attentionVisibleHint: "窗口在前台也提醒。关掉后只在窗口转到后台（切走、被遮挡或最小化）时提醒。",
       currentQuiet: "当前对话不弹通知",
-      currentQuietHint: "等待就发生在你正看着的对话里时只留标签页标记，免得挡住审批卡片；切到后台后照常提醒。",
-      doneVisible: "页面打开时也提醒「回复完成」",
-      doneVisibleHint: "页面在最前也提醒。默认只在切到后台时提醒，避免打扰。",
+      currentQuietHint: "等待就发生在你正看着的对话里时只留标签页标记，免得挡住审批卡片；窗口转到后台后照常提醒。",
+      doneVisible: "窗口在前台时也提醒「回复完成」",
+      doneVisibleHint: "窗口在前台也提醒。默认只在窗口转到后台时提醒，避免打扰。",
       subagentQuiet: "子代理会话不提醒",
       subagentQuietHint: "跳过后台子代理会话（结果由所属主对话的提醒覆盖）；你正打开的那个照常提醒。",
       autoFocus: "点击通知回到对应对话",
@@ -2379,12 +2400,12 @@
       externalCountFailed: "failed ",
       externalNoTargets: "Add at least one push target first.",
       externalOffHint: "Turn on \"Forward to external targets\" first.",
-      attentionVisible: "Also alert \"needs you\" while the page is open",
-      attentionVisibleHint: "Alert even while the page is in front. Turn off to hear only from the background.",
+      attentionVisible: "Also alert \"needs you\" while the window is in front",
+      attentionVisibleHint: "Alert even while the window has focus. Turn off to hear only once the window goes to the background (another app, covered, or minimised).",
       currentQuiet: "Stay quiet for the conversation on screen",
-      currentQuietHint: "A wait belonging to the conversation on screen keeps only the tab marker, so the approval card stays readable; backgrounding restores alerts.",
-      doneVisible: "Also alert \"reply finished\" while the page is open",
-      doneVisibleHint: "Alert even while the page is in front. By default only background finishes alert.",
+      currentQuietHint: "A wait belonging to the conversation on screen keeps only the tab marker, so the approval card stays readable; moving the window to the background restores alerts.",
+      doneVisible: "Also alert \"reply finished\" while the window is in front",
+      doneVisibleHint: "Alert even while the window has focus. By default only finishes in the background alert.",
       subagentQuiet: "Ignore subagent sessions",
       subagentQuietHint: "Skip sessions spawned by a subagent (the parent conversation covers them); the one you have open still alerts.",
       autoFocus: "Click a toast to open that conversation",
@@ -3381,6 +3402,13 @@
           var onVisibility = function () { try { flushQuieted(); } catch (e) {} };
           try { document.addEventListener("visibilitychange", onVisibility); } catch (e) {}
           unsubs.push(function () { try { document.removeEventListener("visibilitychange", onVisibility); } catch (e) {} });
+          // Same re-arm for the other half of "went away": losing window focus.
+          try { window.addEventListener("focus", onPageFocus); } catch (e) {}
+          try { window.addEventListener("blur", onPageBlur); } catch (e) {}
+          unsubs.push(function () {
+            try { window.removeEventListener("focus", onPageFocus); } catch (e) {}
+            try { window.removeEventListener("blur", onPageBlur); } catch (e) {}
+          });
           // Quick-decision bridge: register the worker half of this bundle (a
           // no-op where quickActions is off or a worker cannot run) and start
           // listening for toast-button relays.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-notify-me",
-  "version": "1.10.4",
+  "version": "1.10.5",
   "description": "离开 DSH 页面也能收到提醒：需要你操作 / 后台回复完成时发系统通知、标题标记与可选页面浮层（副屏也能看见），支持审批快捷裁决与外部推送，Web 版与桌面版均可用。",
   "license": "MIT",
   "type": "module",