@cowwo/dsh-icon-custom 0.12.0 → 0.16.0

package/README.zh.md

@@ -58,7 +58,7 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
 规则:
 
 - 数字 = **几个会话**在等你(不是几件事);同一个会话只占一格。
-- 只有子代理会话不计。**你正开着的那个会话也算**——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分;**要清掉它,切走再切回来即可**(你人已经在里面时又结束的那一轮不会自动消,见下一条)。
+- 只有子代理会话不计。**什么算"你在看"**(0.15.2 起):那个会话必须真的显示在主区域的对话里、浏览器标签页在前台(切到别的标签页或最小化不算)、且屏幕上就是它——残留的"最近打开过"不再算数。**这两种"不算"都只是暂停计时,不会因此清掉红点**;真正算"离开"的只有一件事:**去别的会话**(那时它的快照被丢弃,你下次进来待够 N 秒才算看过)。**你正开着的那个会话也算**;**要清掉它,切走再切回来即可**(你人已经在里面时又结束的那一轮不会自动消,见下一条)。
 - **已读记在宿主**(`$DSH_HOME/custom-favicon/unread-seen.json`):进过 = 处理过,刷新/重启不会"复活",**任何一台设备上看过,所有设备都不再提醒**(开着的页面最多约一分钟收敛,刷新则立刻)。浏览器自己也留一份,但只当缓存兼离线队列——所以清站点数据、换浏览器、无痕窗口都不会把"已读"丢回去。装插件之前的历史结束也不算。
 - **可以要求"待够才算已读"**:设置页填一个秒数(默认 0)。填 0 = 进去就算已读(红点立即消失);填 N = 你要在那个会话里**连续待满 N 秒**它才算看过,中途切走就清零重数,刷新页面也重新数。上限 600 秒。
   **计时只认"你进入会话时已经存在的那次结束"**:你人已经在会话里的时候它又跑完一轮,那一轮**不算数**——红点会一直亮着,等你**切走再进来**才消。这样"我正看着的会话跑完了"这件事不会被几秒钟后自动抹掉(0.11.1 起;此前是"停留满 N 秒就把最新那次结束也标成已读",红点只闪一下)。

package/client/client.js

@@ -80,7 +80,7 @@ window.__ModuleLoader__.load({
 			badgeTestHint: "真实未读 = 有会话发生了上面勾选的情况、而且你还没看过它(打开该会话即视为已读)。你正开着的会话也算——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分。只有子代理不计。手动模式:自己填数字试看效果。刷新页面后回到真实未读。",
 			clearDelayLabel: "进入会话后多久算已读:",
 			clearDelayUnit: "秒",
-			clearDelayHint: "填 0 = 进去就算已读(红点立即消失)。大于 0 时,你要在那个会话里连续待满这么多秒它才算看过:中途切走会清零重数,刷新页面也重新数。**计时只认\"你进入会话时已经存在的结束\"**——你人已经在里面的时候又跑完一轮,那一轮不算数:它会一直亮着,等你切走再进来才会清。上限 600 秒。已读记在宿主($DSH_HOME/custom-favicon/unread-seen.json):任何一台设备上看过,所有设备都不再提醒;浏览器那份只是缓存,清站点数据不会把已读丢回去。"
+			clearDelayHint: "填 0 = 进去就算已读(红点立即消失)。大于 0 时,你要在那个会话里连续待满这么多秒它才算看过:中途切走会清零重数,刷新页面也重新数。**计时只认\"你进入会话时已经存在的结束\"**——你人已经在里面的时候又跑完一轮,那一轮不算数:它会一直亮着,等你切走再进来才会清。上限 600 秒。**切到「插件/设置」页、或把标签页切到后台,都只是暂停计时,不会因此清掉红点**(它们不算离开);真正算离开的只有一件事:**去别的会话**。已读记在宿主($DSH_HOME/custom-favicon/unread-seen.json):任何一台设备上看过,所有设备都不再提醒;浏览器那份只是缓存,清站点数据不会把已读丢回去。"
 		};
 		const en = {
 			nav: "Favicon",
@@ -153,7 +153,7 @@ window.__ModuleLoader__.load({
 			badgeTestHint: "Real unread = a session ended for one of the checked reasons and you have not looked at it yet (opening a session marks it read). The session you are viewing counts too — the window may be minimised or the page in the background, so this half cannot tell whether you are looking, and does not pretend to. Only sub-agents never count. Manual = type a number to preview. Resets to Real on reload.",
 			clearDelayLabel: "Mark read after staying:",
 			clearDelayUnit: "seconds",
-			clearDelayHint: "0 = read as soon as you enter (the dot clears at once). Above 0 you must stay in that session for this many seconds before it counts as read: leaving it resets the clock, and so does a reload. The clock only ever covers **the ending that was already there when you entered** — a turn that finishes while you are sitting in the session does not count: it stays red until you leave and come back. Capped at 600 seconds. Read state lives on the Host ($DSH_HOME/custom-favicon/unread-seen.json): read on any device means read on every device, and the browser's own copy is only a cache — clearing site data no longer throws it away."
+			clearDelayHint: "0 = read as soon as you enter (the dot clears at once). Above 0 you must stay in that session for this many seconds before it counts as read: leaving it resets the clock, and so does a reload. The clock only ever covers **the ending that was already there when you entered** — a turn that finishes while you are sitting in the session does not count: it stays red until you leave and come back. Capped at 600 seconds. A settings or plugins page, or a tab in the background, only **pauses** the clock — neither clears a dot (neither counts as leaving); the one thing that does count as leaving is **opening another session**. Read state lives on the Host ($DSH_HOME/custom-favicon/unread-seen.json): read on any device means read on every device, and the browser's own copy is only a cache — clearing site data no longer throws it away."
 		};
 		//#endregion
 
@@ -562,23 +562,77 @@ window.__ModuleLoader__.load({
 			}
 			return changed;
 		}
+		/**
+		 * Whether this page is on screen at all.
+		 *
+		 * A hidden tab is not "being looked at": the clock must not run while the page
+		 * is in the background, or a session left open in another tab would be marked
+		 * read for every device. Unknown (an exotic embedder) counts as visible, which
+		 * is the pre-0.12.1 behaviour.
+		 * @returns whether the page is visible.
+		 */
+		function documentVisible() {
+			try { return document.visibilityState !== "hidden"; } catch { return true; }
+		}
+		/**
+		 * The session whose conversation the page is rendering right now, from the DOM.
+		 *
+		 * This is the only signal that names the session on screen, and it is the one
+		 * that keeps a stale retention from clearing a dot: `retainedBy.mainView` means
+		 * "recently opened, not yet released", not "displayed". `undefined` means this
+		 * build carries no such marker (or the probe failed) and callers must fall back
+		 * to the retention answer rather than treat it as "nothing is displayed".
+		 * @returns the session id, or undefined when the page cannot say.
+		 */
+		function displayedSessionId() {
+			try {
+				const node = document.querySelector("[data-conversation-session]");
+				if (node === null) return undefined;
+				const id = node.getAttribute("data-conversation-session");
+				return typeof id === "string" && id !== "" ? id : undefined;
+			} catch { return undefined; }
+		}
 		/**
 		 * Every session the main view is showing.
 		 *
-		 * The official signal is the row's `retainedBy.mainView` retention count, the
-		 * same one ui-layout's DocumentTitle, ui-cordis, ui-open-in-app and ui-session
-		 * read (`list.current` is honoured first for runtimes that expose it).
+		 * `view` carries what the page itself says about the screen:
+		 *   * `panelActive` — a global panel (settings, plugins, …) replaced the
+		 *     conversation. DSH's own sidebar treats that as "no current session"
+		 *     (`usePanelInfo((info) => info.activePanelId !== null)`), and following it
+		 *     is what fixes the "cleared a dot I never opened" report: the conversation
+		 *     is simply not on screen.
+		 *   * `visible` — whether this page is on screen at all.
+		 *   * `displayed` — the session the conversation is rendering, when the DOM can
+		 *     name it. That is the precise answer and it wins over retention.
+		 *
+		 * Retention (`retainedBy.mainView`) stays as the fallback: it is what shipped
+		 * before, it keeps working on a build without the newer signals, and its known
+		 * weakness (a release that lags behind the pane) only costs a false "read" when
+		 * nothing better is available.
+		 * @param list - the session list snapshot (may be absent).
+		 * @param view - the screen report described above (may be absent).
+		 * @returns the ids being viewed, in list order; `[]` when there are none.
+		 */
+		/**
+		 * Which session this page is ON — the set that defines "entered" and "left".
+		 *
+		 * Only a change here counts as leaving a session, so this must NOT be emptied
+		 * by pausing: a background tab, or a global panel (settings, plugins, …) that
+		 * covers the conversation, keeps you on the same session. Emptying it would
+		 * drop the entered-at snapshot, and taking a fresh one on return is exactly
+		 * what acknowledges an ending you never left the session for — the bug behind
+		 * "切一下标签页红点就没了".
 		 *
-		 * It returns ALL of them, not one. The pane retains the incoming session
-		 * BEFORE it releases the outgoing one, and a retention that outlives its pane
-		 * can leave an old session looking "current" for good — and picking a single
-		 * id then meant the session you were actually reading was never marked read:
-		 * the dot stayed red however long you stayed in it. Each retained session
-		 * gets its own stay clock instead.
+		 * `view.displayed` (read from the DOM) is the precise answer when available;
+		 * `list.current` and then retention are the fallbacks, which is also what keeps
+		 * the answer meaningful while a panel covers the conversation.
 		 * @param list - the session list snapshot (may be absent).
+		 * @param view - `{ displayed }`: the session the conversation is rendering.
 		 * @returns the ids being viewed, in list order; `[]` when there are none.
 		 */
-		function currentSessionIds(list) {
+		function currentSessionIds(list, view) {
+			const screen = view !== null && typeof view === "object" ? view : {};
+			if (typeof screen.displayed === "string" && screen.displayed !== "") return [screen.displayed];
 			if (list === null || typeof list !== "object") return [];
 			if (typeof list.current === "string" && list.current !== "") return [list.current];
 			const byId = list.byId;
@@ -1081,15 +1135,45 @@ window.__ModuleLoader__.load({
 				// Never silent: a failure here is invisible in the UI (the tab simply
 				// keeps its previous icon), which once cost a whole debugging session.
 				// Warn once per distinct reason so the 5s watchdog cannot spam.
-				const why = String((error && error.message) || error);
-				if (why !== lastComposeError) {
-					lastComposeError = why;
-					try { console.warn("dsh-icon-custom: 标签页红点合成失败 / favicon badge compose failed:", why); } catch {}
-				}
+				warnFaviconCompose(error);
 			} finally {
 				if (seq === composeSeq) faviconComposing = false;
 			}
 		}
+		/**
+		 * Report a failed tab-icon composition, once per distinct reason.
+		 *
+		 * The 5-second watchdog retries, so repeating the same line would bury the
+		 * console in noise; a NEW reason is exactly the signal worth seeing.
+		 * @param error - whatever the compose threw.
+		 */
+		function warnFaviconCompose(error) {
+			const why = String((error && error.message) || error);
+			if (why === lastComposeError) return;
+			lastComposeError = why;
+			try { console.warn("dsh-icon-custom: 标签页红点合成失败 / favicon badge compose failed:", why); } catch {}
+		}
+		/**
+		 * Fire-and-forget composition whose failures are still reported.
+		 *
+		 * `applyBadgeToFavicon` is async, so it never throws synchronously: a caller's
+		 * `try { ... } catch {}` (the badge listeners all have one) cannot see its
+		 * rejection, and the tab icon would simply never change with nothing in the
+		 * console — the exact "no warning, no badge" state. Every call site goes through
+		 * here instead.
+		 * @param count - sessions needing you; 0 restores the plain icon.
+		 * @param size - badge size key.
+		 */
+		function composeFavicon(count, size) {
+			try {
+				Promise.resolve(applyBadgeToFavicon(count, size)).catch(warnFaviconCompose);
+			} catch (error) {
+				// An `async` callee never throws synchronously, so this arm is dead TODAY —
+				// it is here so a future refactor (an early-returning sync path) cannot
+				// quietly reintroduce the silent "no warning, no badge" state.
+				warnFaviconCompose(error);
+			}
+		}
 		/**
 		 * Re-assert the tab badge after anything outside this plugin disturbed the
 		 * icon link — a cached page, a browser extension, a tab move, or a plugin
@@ -1106,17 +1190,17 @@ window.__ModuleLoader__.load({
 				// Carries the custom icon, or puts the shipped pair back. Both writers
 				// only touch a link that actually differs, so this stays a no-op once
 				// the page is correct and cannot re-arm the head observer.
-				applyBadgeToFavicon(0);
+				composeFavicon(0);
 				return;
 			}
 			if (ours || faviconComposing) return; // already showing, or a build is running
-			applyBadgeToFavicon(effectiveCount(), badgeSize);
+			composeFavicon(effectiveCount(), badgeSize);
 		}
 		// A freshly applied base icon replaces whatever the browser holds, so the
 		// composite must be rebuilt from the NEW base instead of the stale one.
 		function refreshFaviconBase() {
 			faviconBase = null;
-			applyBadgeToFavicon(effectiveCount(), badgeSize);
+			composeFavicon(effectiveCount(), badgeSize);
 		}
 		//#endregion
 
@@ -1688,7 +1772,26 @@ window.__ModuleLoader__.load({
 				pruneSeenState();
 				saveSeenState();
 			}, [list]);
-			const currentIds = currentSessionIds(list);
+			// What the page says about the screen, refreshed on the two moments that can
+			// change it without the session list changing: a global panel replacing the
+			// conversation (its own standard prop, the same one the shipped sidebar reads)
+			// and the tab going to the background. Both are read here, not inferred, so
+			// "you are looking at it" stops being a guess about stale retention.
+			// Pausing signals, NOT leaving signals: they stop the stay clock without
+			// touching which session this page is on (so the entered-at snapshot
+			// survives). Only switching to another session counts as leaving.
+			const panelActive = typeof props.usePanelInfo === "function"
+				? props.usePanelInfo((info) => info !== null && typeof info === "object" && info.activePanelId !== null)
+				: false;
+			const [visible, setVisible] = React.useState(documentVisible);
+			React.useEffect(() => {
+				const onVisibility = () => setVisible(documentVisible());
+				window.addEventListener("visibilitychange", onVisibility);
+				return () => window.removeEventListener("visibilitychange", onVisibility);
+			}, []);
+			/** Looking at the conversation right now: on screen, and this tab in front. */
+			const watching = visible && panelActive !== true;
+			const currentIds = currentSessionIds(list, { displayed: displayedSessionId() });
 			const items = collectUnread(list, pending, config, seenState.seen);
 			const count = items.length;
 			// Being in a session is what marks it read — and the clock that does it is
@@ -1725,8 +1828,10 @@ window.__ModuleLoader__.load({
 			/**
 			 * Entered-at snapshot: `id → endAt` as it stood when that session joined
 			 * the view. Deliberately NOT refreshed while the session stays — that is
-			 * the rule ("an ending during your stay waits for the next entry"). A
-			 * session that leaves is forgotten, so coming back takes a fresh snapshot.
+			 * the rule ("an ending during your stay waits for the next entry"). Only a
+			 * session that LEAVES the view is forgotten, so coming back to it takes a
+			 * fresh snapshot; pausing (background tab, a global panel) keeps both the
+			 * session and its snapshot.
 			 */
 			const stayArmed = React.useRef(new Map());
 			React.useEffect(() => {
@@ -1738,7 +1843,10 @@ window.__ModuleLoader__.load({
 				for (const id of stayIds) {
 					if (!stayArmed.current.has(id)) stayArmed.current.set(id, lastTurnEndAt(snapshot[id]));
 				}
-				if (staySignature === "") return undefined;
+				// Paused: nothing may be acknowledged while nobody is watching, but the
+				// snapshots above stay put — that is what makes resuming continue the
+				// same entry instead of silently re-entering it.
+				if (staySignature === "" || watching !== true) return undefined;
 				const armed = stayIds.map((id) => ({ id, endAt: stayArmed.current.get(id) }));
 				let cancelled = false;
 				let timer = 0;
@@ -1759,7 +1867,7 @@ window.__ModuleLoader__.load({
 					cancelled = true;
 					if (timer !== 0) window.clearTimeout(timer);
 				};
-			}, [staySignature, delayMs]);
+			}, [staySignature, delayMs, watching]);
 			React.useEffect(() => { emitRealBadge(count, items); }, [count, items]);
 			// Map session → its Workspace from the official snapshot: the ID anchors the
 			// folder dot to the keyed row, the title is what the row displays (not always
@@ -2741,15 +2849,15 @@ window.__ModuleLoader__.load({
 			// this effect keeps the tab icon in sync. Teardown restores the
 			// pristine platform/custom icon.
 			ctx.effect(() => {
-				const unsubscribe = subscribeBadge((snapshot) => { applyBadgeToFavicon(snapshot.count, snapshot.size); });
+				const unsubscribe = subscribeBadge((snapshot) => { composeFavicon(snapshot.count, snapshot.size); });
 				// Level-triggered on purpose: (re)applying this half must adopt the
 				// value that is already on the bridge. The brand mark reads it at
 				// mount; the tab icon has to be told, or a plugin hot-reload would
 				// leave it restored (the old effect's cleanup) until the next change.
-				applyBadgeToFavicon(effectiveCount(), badgeSize);
+				composeFavicon(effectiveCount(), badgeSize);
 				return () => {
 					unsubscribe();
-					applyBadgeToFavicon(0);
+					composeFavicon(0);
 				};
 			}, "dsh-icon-custom: favicon badge");
 			// Watchdog. The tab icon is the one surface other parties can disturb
@@ -2826,7 +2934,7 @@ window.__ModuleLoader__.load({
 			}, "dsh-icon-custom: workspace dots");
 			// The platform favicon.svg repaints itself for dark mode through
 			// prefers-color-scheme; a composited bitmap cannot, so rebuild it.
-			ctx.on("theme/change", () => { applyBadgeToFavicon(effectiveCount(), badgeSize); });
+			ctx.on("theme/change", () => { composeFavicon(effectiveCount(), badgeSize); });
 		}
 		exports.apply = apply;
 		exports.inject = inject;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cowwo/dsh-icon-custom",
-  "version": "0.12.0",
+  "version": "0.16.0",
   "description": "自定义浏览器标签页图标:在设置页上传 SVG/PNG/ICO,立即生效并持久保存,自动适配安卓/iOS/平板 PWA 图标,并可把未读数字显示为系统应用图标角标(Windows 任务栏)。· Custom browser tab favicon: upload SVG/PNG/ICO from the settings page, applies instantly and persists, auto-sizes PWA icons for Android/iOS/tablets, and projects the unread count onto the system app-icon badge (Windows taskbar).",
   "type": "module",
   "main": "lib/index.js",