@cowwo/dsh-icon-custom 0.15.0 → 0.16.0

package/README.zh.md

@@ -58,7 +58,7 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
 规则:
 
 - 数字 = **几个会话**在等你(不是几件事);同一个会话只占一格。
-- 只有子代理会话不计。**什么算"你在看"**(0.12.1 起):那个会话必须真的显示在主区域的对话里(切到「插件 / 设置」这类页面不算)、浏览器标签页在前台(切到别的标签页或最小化不算)、且屏幕上就是它——残留的"最近打开过"不再算数。**你正开着的那个会话也算**;**要清掉它,切走再切回来即可**(你人已经在里面时又结束的那一轮不会自动消,见下一条)。
+- 只有子代理会话不计。**什么算"你在看"**(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. It only counts while that session is really on screen in the foreground tab: a settings or plugins page, or a tab in the background, is not \"being looked at\". 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
 
@@ -613,10 +613,25 @@ window.__ModuleLoader__.load({
 		 * @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
+		 * "切一下标签页红点就没了".
+		 *
+		 * `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, view) {
 			const screen = view !== null && typeof view === "object" ? view : {};
-			if (screen.visible === false) return [];
-			if (screen.panelActive === true) return [];
 			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];
@@ -1120,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
@@ -1145,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
 
@@ -1732,6 +1777,9 @@ window.__ModuleLoader__.load({
 			// 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;
@@ -1741,7 +1789,9 @@ window.__ModuleLoader__.load({
 				window.addEventListener("visibilitychange", onVisibility);
 				return () => window.removeEventListener("visibilitychange", onVisibility);
 			}, []);
-			const currentIds = currentSessionIds(list, { panelActive, visible, displayed: displayedSessionId() });
+			/** 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
@@ -1778,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(() => {
@@ -1791,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;
@@ -1812,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
@@ -2794,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
@@ -2879,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.15.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",