@cowwo/dsh-icon-custom 0.10.2 → 0.11.1

package/README.md

@@ -43,6 +43,38 @@ Notes:
 - It can be toggled at any time after upload — no re-upload needed.
 - This only affects the sidebar brand mark (the one next to `deepseek HARNESS`); PWA/installed-app icons are a separate option above.
 
+## App icon badge (the red dot on the system icon)
+
+Once the page is **installed as an app**, the same unread number is also shown on the **system icon**. The switch lives in **Settings → icon管理 → unread badge** ("Badge the system app icon") and is **on by default**; the number is **exactly the page number** (one computation, no extra clamping), so the two can never disagree.
+
+> ⚠️ **What it looks like on Windows depends on which browser installed the app**:
+> - **Installed with Chrome**: Chrome **draws its own overlay icon** on the taskbar button — a **dark circle with the white number**, at the lower-right of the icon. **Not a red dot, and not part of our artwork.** Above 99 it shows `99+`.
+> - **Installed with Edge**: Edge goes through the **Windows badge channel**, so the badge uses the system style. Microsoft's docs say both empty and numeric badges are supported, but on Windows 11 this machine still drew only a system-blue dot when calling `navigator.setAppBadge(7)` directly from DevTools (2026-10-01). The plugin now has a **5-second low-frequency watchdog** that keeps re-asserting a positive number, but whether Edge/Windows renders it as a number or a dot is ultimately up to the system. For a reliable number, installing with Chrome is the current workaround.
+>
+> Either way it exists **only while the app window is open**: close the window and it is gone (that is not a bug), and nothing can refresh it afterwards (there is no push server, so with no page running there is no code running).
+
+Platform support as of 0.11.1:
+
+| Platform | Badge | Status |
+|---|---|---|
+| Windows **Chrome** 81+ | Dark circle + **white number** (Chrome's own overlay icon, lower-right) | Confirmed by Chrome's docs screenshot + Chromium source; **not yet measured on this machine** |
+| Windows **Edge** 81+ | Goes through the Windows badge channel; Microsoft's docs support numbers, but this machine measured the number being drawn as a dot | **Measured anomaly** (2026-10-01) |
+| macOS Chrome / Edge 81+ | Dock badge | Unverified (the code is ready; same single call) |
+| macOS Safari 17+ ("Add to Dock") | Dock badge | Unverified |
+| iOS / iPadOS Safari 16.4+ (Add to Home Screen) | Number on the home-screen icon | Unverified; and it appears **only after notifications have been granted** — this plugin does not request that permission yet, so no badge on iOS for now |
+| Android Chrome / Edge | — | **Not supported by the system**: Chromium compiles the badge implementation out on Android, and a launcher dot can only come from a **notification** (this plugin posts none) |
+| HarmonyOS | — | No public evidence of any implementation; **expected unsupported** (native badges there are ArkTS-only) |
+| Firefox / Linux Chromium | — | No API / no OS API — calls resolve and do nothing |
+
+The "Current environment" line in the settings page reports **local facts only** (secure context? API present? installed as an app?). It never promises a badge will appear, because **detecting the API is not delivery** (that is exactly the Android and Linux case, and iOS adds a permission on top). Whether it really shows is up to the system.
+
+Two behaviours that look like bugs but are not:
+
+- **A "manual test" number typed in a normal browser tab produces no taskbar badge** — correct: the badge belongs to the **installed app window**; a plain tab's call is silently ignored.
+- **No badge when the page is reached over LAN `http://192.168.x.x`** — the Badging API requires a secure context; the settings page then says to use localhost or https.
+
+The reasoning (why no notifications, why no service worker, why no platform gating) is recorded in [`docs/adr/0005-app-icon-badge.md`](./docs/adr/0005-app-icon-badge.md).
+
 ## Format support
 
 - **SVG** — recognized by content (`<svg`), validated against script / event‑handler / `javascript:` injection. Rasterized to PNG in the browser before upload.

package/README.zh.md

@@ -58,14 +58,47 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
 规则:
 
 - 数字 = **几个会话**在等你(不是几件事);同一个会话只占一格。
-- 只有子代理会话不计。**你正开着的那个会话也算**——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分;要清掉它,切走再切回来即可。
+- 只有子代理会话不计。**你正开着的那个会话也算**——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分;**要清掉它,切走再切回来即可**(你人已经在里面时又结束的那一轮不会自动消,见下一条)。
 - **已读记在每个浏览器自己身上**(localStorage):进过 = 处理过,刷新/重启不会"复活";装插件之前的历史结束也不算。
-- **可以要求"待够才算已读"**:设置页填一个秒数(默认 0)。填 0 = 进去就算已读(红点立即消失);填 N = 你要在那个会话里**连续待满 N 秒**它才算看过——中途切走、或它又跑完一轮,都清零重数,刷新页面也重新数。上限 600 秒。
+- **可以要求"待够才算已读"**:设置页填一个秒数(默认 0)。填 0 = 进去就算已读(红点立即消失);填 N = 你要在那个会话里**连续待满 N 秒**它才算看过,中途切走就清零重数,刷新页面也重新数。上限 600 秒。
+  **计时只认"你进入会话时已经存在的那次结束"**:你人已经在会话里的时候它又跑完一轮,那一轮**不算数**——红点会一直亮着,等你**切走再进来**才消。这样"我正看着的会话跑完了"这件事不会被几秒钟后自动抹掉(0.11.1 起;此前是"停留满 N 秒就把最新那次结束也标成已读",红点只闪一下)。
 - 数据全部来自官方:`turn/end` 事件经官方 session projection 折叠,加上官方的"等待交互"注册表——**不依赖任何其他插件**。
 - 设置页的**数据来源**可以切到"手动测试",手填数字试看效果。
 - **工作区和会话行上的红点(实验)**:侧栏每个**工作区**那一行的文件夹图标右上角一个小红点,每个**有未读的会话**在标题右边跟一个小红点——一眼看出"事情在哪个工作区的哪个会话"。这一项是**贴着页面结构**做的——DSH 大版本升级后**可能失效**,失效时只会变成"不显示",**不影响**红点数字、清单和跳转;设置页里有一个开关可以随时关掉它。
 - **想知道具体是哪个会话?** 侧栏「工作区」标题的**右上角**有一个**红底数字**(没有待处理时是灰色 0,位置不变);点开是待处理会话清单,**按工作区分组**(工作区名 · 会话名 · 在等你/刚结束),点其中一条**直接跳到那个会话**。
 
+## 应用图标角标(系统图标上的红点)
+
+把网页**安装为应用**后,同一个未读数字也会显示在**系统图标**上。设置在**设置 → icon管理 → 未读红点**里的「在系统应用图标上显示红点」,**默认打开**;数字与页内红点**严格同值**(同一份计算,不额外截断),所以两个地方永远一致。
+
+> ⚠️ **Windows 上它长什么样——取决于你用什么浏览器装**:
+> - **Chrome 装的**:Chrome **自己画**一张覆盖图标贴在任务栏按钮上——**深灰圆 + 白色数字**,位置在图标右下角。**不是红色圆点,也不是我们图标的一部分**。数字超过 99 显示 `99+`。
+> - **Edge 装的**:Edge 走 **Windows 系统徽章通道**,外观是系统样式。官方文档说支持数字和空角标,但本机在 Windows 11 上实测(2026-10-01)控制台直接 `navigator.setAppBadge(7)` 也只出现一个系统蓝点。插件已加 **5 秒低频看门狗**,会持续重设正向数字,但最终画成数字还是点由 Edge/Windows 决定;想要稳定数字,可用 Chrome 安装。
+>
+> 两种情况下都:**只在应用窗口开着的时候存在**——关掉窗口角标就消失(这不是插件坏了),窗口全关之后也不会再更新数字(没有推送服务,页面不在就没有代码在跑)。
+
+平台支持情况(截至 0.11.1):
+
+| 平台 | 角标 | 状态 |
+|---|---|---|
+| Windows **Chrome** 81+ | 深灰圆 + **白色数字**(Chrome 自己画的覆盖图标,右下角) | 官方文档示例图 + 源码印证;**本机待实测** |
+| Windows **Edge** 81+ | 走 Windows 系统徽章通道;官方文档支持数字,但本机实测数字被画成点(待 Edge/Windows 侧修复) | **本机实测异常**(2026-10-01) |
+| macOS Chrome / Edge 81+ | Dock 角标 | 未验证(代码已就绪,同一行不会额外做事) |
+| macOS Safari 17+(「添加到程序坞」) | Dock 角标 | 未验证 |
+| iOS / iPadOS Safari 16.4+(加到主屏) | 主屏图标上的数字 | 未验证;且**必须先授予通知权限**才会显示——本插件目前不申请通知权限,所以 iOS 上暂时不会出现 |
+| Android Chrome / Edge | —— | **系统不支持**:Chromium 在安卓上把角标实现编译掉了;启动器上的圆点只能由**通知**产生(本插件不发通知) |
+| 鸿蒙 | —— | 无任何公开实现证据,**预计不支持**(鸿蒙的原生角标只能用 ArkTS 设) |
+| Firefox / Linux Chromium | —— | 不支持 / 没有系统 API,调用静默无效 |
+
+设置页里那行「当前环境」只报**本机此刻的事实**(是不是安全上下文、有没有这个 API、是不是已安装的应用),它**不**承诺角标一定会出现——因为**探测到 API ≠ 会显示**(安卓、Linux 上就是如此;iOS 还多一道通知权限)。是否真正显示由系统决定。
+
+顺便说明两个容易被当成 bug 的现象:
+
+- **在浏览器标签页里填「手动测试」数字,任务栏没有角标** —— 这是对的:角标只属于**安装后的应用窗口**,普通标签页调用是静默无操作。
+- **局域网 `http://192.168.x.x` 访问时没有角标** —— Badging API 要求安全上下文,这时设置页会提示"请用 localhost 或 https 访问"。
+
+设计取舍(为什么不做通知、不做 service worker、为什么不按平台门禁)记在 [`docs/adr/0005-app-icon-badge.md`](./docs/adr/0005-app-icon-badge.md)。
+
 ## 支持的格式
 
 - **SVG** — 按内容(`<svg`)识别,并拦截 `<script>` / 事件属性 / `javascript:` 注入。上传前会在浏览器里栅格化成 PNG。

package/client/client.js

@@ -70,10 +70,17 @@ window.__ModuleLoader__.load({
 			ageYears: "{n}年",
 			workspaceDotLabel: "在工作区和会话行上显示红点(实验)",
 			workspaceDotHint: "在侧栏工作区那一行的文件夹图标上点一个小红点。这一项是贴着页面结构做的,DSH 升级后可能失效;失效时只会变成\"不显示\",不会影响红点数字、清单、跳转这些功能,随时可以关掉它。",
+			appBadgeLabel: "在系统应用图标上显示红点",
+			appBadgeHint: "安装为应用后,把同一个数字也放到系统图标上:Windows 是任务栏图标上的角标,macOS 是 Dock 角标,iOS 是主屏图标上的数字。样子由系统决定——Windows 上 Chrome 画深色圆+白字,Edge 走 Windows 系统徽章通道(是否显示数字由 Edge/Windows 决定);插件会周期重设数字,但只在应用窗口开着时更新。",
+			appBadgeFootnote: "角标只在应用窗口开着时由本插件更新;数字超过 99 时由系统显示为 99+。",
+			appBadgeProbeInstalled: "当前环境:已安装为应用,本机可以设置角标。是否真正显示由系统决定。",
+			appBadgeProbeTab: "当前环境:浏览器标签页(不是安装的应用)——安装为应用后才会显示角标。",
+			appBadgeProbeUnsupported: "当前环境:本机没有这个能力(当前浏览器不支持应用角标)。",
+			appBadgeProbeInsecure: "当前环境:不是安全上下文(请用 localhost 或 https 访问),系统角标不可用。",
 			badgeTestHint: "真实未读 = 有会话发生了上面勾选的情况、而且你还没看过它(打开该会话即视为已读)。你正开着的会话也算——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分。只有子代理不计。手动模式:自己填数字试看效果。刷新页面后回到真实未读。",
 			clearDelayLabel: "进入会话后多久算已读:",
 			clearDelayUnit: "秒",
-			clearDelayHint: "填 0 = 进去就算已读(红点立即消失)。大于 0 时,你要在那个会话里连续待满这么多秒它才算看过:中途切走、或它又跑完一轮,都会清零重数;刷新页面也重新数。上限 600 秒。"
+			clearDelayHint: "填 0 = 进去就算已读(红点立即消失)。大于 0 时,你要在那个会话里连续待满这么多秒它才算看过:中途切走会清零重数,刷新页面也重新数。**计时只认\"你进入会话时已经存在的结束\"**——你人已经在里面的时候又跑完一轮,那一轮不算数:它会一直亮着,等你切走再进来才会清。上限 600 秒。"
 		};
 		const en = {
 			nav: "Favicon",
@@ -136,10 +143,17 @@ window.__ModuleLoader__.load({
 			ageYears: "{n}y",
 			workspaceDotLabel: "Dots on workspace and session rows (experimental)",
 			workspaceDotHint: "Adds a small red dot to the folder icon of each workspace row. This one reads the page structure, so a DSH upgrade may break it; when it does it simply stops showing, never affecting the counts, the list, or navigation. Turn it off any time.",
+			appBadgeLabel: "Badge the system app icon",
+			appBadgeHint: "Once installed as an app, the same number also goes to the system icon: a taskbar badge on Windows, a Dock badge on macOS, a number on the iOS home-screen icon. The system decides how it looks — on Windows, Chrome draws a dark circle with white text, while Edge goes through the Windows badge channel (whether it shows the number is up to Edge/Windows). The plugin re-asserts the number periodically, but only while the app window is open.",
+			appBadgeFootnote: "The badge is only updated by this plugin while the app window is open; above 99 the system shows 99+.",
+			appBadgeProbeInstalled: "This environment: installed as an app, so this device can set a badge. Whether it actually appears is up to the system.",
+			appBadgeProbeTab: "This environment: a browser tab (not an installed app) — install as an app to get a badge.",
+			appBadgeProbeUnsupported: "This environment: no app-badge capability in this browser.",
+			appBadgeProbeInsecure: "This environment: not a secure context (use localhost or https) — the system badge is unavailable.",
 			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, or a fresh ending in it, resets the clock, and so does a reload. Capped at 600 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."
 		};
 		//#endregion
 
@@ -255,7 +269,9 @@ window.__ModuleLoader__.load({
 		const UNREAD_FALLBACK_REASONS = { completed: true, error: true, blocked: true, "max-tokens": true, interrupted: true, "aborted:user": false, "aborted:other": true };
 		/** Mirror of the host's cap (see lib/unread.js) — 10 minutes. */
 		const UNREAD_CLEAR_DELAY_MAX_SEC = 600;
-		let unreadConfig = { reasons: { ...UNREAD_FALLBACK_REASONS }, pending: true, workspaceDot: true, clearDelaySec: 0 };
+		/** Mirror of the host's default (see lib/unread.js) — badging the app icon is on. */
+		const UNREAD_APP_BADGE_FALLBACK = true;
+		let unreadConfig = { reasons: { ...UNREAD_FALLBACK_REASONS }, pending: true, workspaceDot: true, appBadge: UNREAD_APP_BADGE_FALLBACK, clearDelaySec: 0 };
 		const unreadConfigListeners = new Set();
 		/** Mirror of the host's normalizer: any input becomes an integer 0..cap seconds. */
 		function normalizeClearDelay(input) {
@@ -276,12 +292,16 @@ window.__ModuleLoader__.load({
 				reasons,
 				pending: typeof source.pending === "boolean" ? source.pending : true,
 				workspaceDot: typeof source.workspaceDot === "boolean" ? source.workspaceDot : true,
+				appBadge: typeof source.appBadge === "boolean" ? source.appBadge : UNREAD_APP_BADGE_FALLBACK,
 				clearDelaySec: normalizeClearDelay(source.clearDelaySec)
 			};
 		}
 		function emitUnreadConfig(input) {
 			unreadConfig = normalizeUnreadConfig(input);
 			unreadConfigListeners.forEach((fn) => { try { fn(unreadConfig); } catch {} });
+			// The rule (or just the app-badge switch) moved: the OS badge follows it
+			// in the same breath, so toggling it applies without a reload.
+			reconcileAppBadge();
 		}
 		function subscribeUnreadConfig(fn) {
 			unreadConfigListeners.add(fn);
@@ -431,25 +451,6 @@ window.__ModuleLoader__.load({
 			const value = values !== null && typeof values === "object" ? values[LAST_TURN_END_KEY] : undefined;
 			return value !== null && typeof value === "object" && typeof value.endAt === "number" ? value.endAt : 0;
 		}
-		/**
-		 * What the "stay here long enough" timer is armed for, or "" when nothing
-		 * should be armed.
-		 *
-		 * Keyed on the session's own `lastTurnEnd.endAt`, deliberately NOT on the
-		 * collected item's `at`: a "waiting for you" item carries `at: Date.now()`,
-		 * which changes on every evaluation — keying on that would tear the timer
-		 * down and re-arm it forever, and a waiting session could never be marked
-		 * read. Including `endAt` is also what makes a NEW ending restart the clock
-		 * instead of inheriting the previous one's progress.
-		 * @param sessionId - the session being viewed.
-		 * @param list - the session list snapshot.
-		 * @returns the key, or "" when there is no session to arm for.
-		 */
-		function stayKeyFor(sessionId, list) {
-			if (typeof sessionId !== "string" || sessionId === "") return "";
-			const byId = list !== null && typeof list === "object" && list.byId !== null && typeof list.byId === "object" ? list.byId : {};
-			return `${sessionId}\u0000${lastTurnEndAt(byId[sessionId])}`;
-		}
 		/**
 		 * How many sessions deserve the badge right now: endings whose reason is
 		 * enabled and that this browser has not seen since, plus sessions waiting
@@ -557,6 +558,8 @@ window.__ModuleLoader__.load({
 			// The header badge is a DOM node, not a listener, so it is reconciled
 			// here as well as from the mutation watchdog. Idempotent either way.
 			paintHeaderBadge();
+			// Same number, second consumer: the OS badge behind the app icon.
+			reconcileAppBadge();
 		}
 		/** Manual test input. */
 		function emitBadge(value) {
@@ -588,6 +591,180 @@ window.__ModuleLoader__.load({
 			return count > 99 ? "99+" : String(count);
 		}
 
+		//#endregion
+		//#region app badge (OS app icon)
+		// The badge the OPERATING SYSTEM draws on the icon of the installed app: the
+		// taskbar overlay on Windows, the Dock badge on macOS, the number on an iOS
+		// home-screen icon. It is the same number the page badge shows, projected
+		// onto the system icon — one number, two consumers.
+		//
+		// Three facts shape this region (all checked against primary sources; see
+		// docs/adr/0005-app-icon-badge.md):
+		//   * detecting the API is NOT delivery. Chromium on Android exposes
+		//     `setAppBadge` and silently ignores it, and iOS only draws the badge
+		//     once notifications have been granted. So the probe reports LOCAL facts
+		//     and never promises that a badge will appear;
+		//   * the OS owns the rendering. On Windows the badge is a browser-drawn
+		//     overlay on the taskbar button of an OPEN window: closing the window
+		//     drops it, and nothing can refresh it afterwards (no push server);
+		//   * the API is write-only, so this half keeps its own count — the very
+		//     `effectiveCount()` the favicon and the header badge already use.
+		//
+		// Everything that DECIDES is a pure function, so a test drives it with no
+		// browser at all; exactly one function touches the API.
+		/** Display modes that mean "this window IS the installed app", not a tab. */
+		const APP_DISPLAY_MODES = ["standalone", "fullscreen", "minimal-ui", "window-controls-overlay"];
+
+		/**
+		 * Normalize what this device is, as three independent local facts.
+		 *
+		 * Deliberately NOT "does this platform support it": the method that works
+		 * on Windows resolves and does nothing on Android, and Apple draws the
+		 * badge only after notifications are granted. Neither is answerable from
+		 * inside the page, so the probe stays silent about them and the copy says
+		 * "whether it actually appears is up to the system" instead.
+		 * @param env - `{ secure, hasApi, installed }`; anything non-boolean reads false.
+		 * @returns the same three flags, normalized.
+		 */
+		function badgeCapabilityProbe(env) {
+			const source = env !== null && typeof env === "object" ? env : {};
+			return {
+				secure: source.secure === true,
+				hasApi: source.hasApi === true,
+				installed: source.installed === true
+			};
+		}
+
+		/**
+		 * Read those facts off the window this code runs in.
+		 *
+		 * "Installed" is a display-mode match rather than `standalone` alone: the
+		 * platform manifest asks for `fullscreen`, so an installed window matches
+		 * THAT mode, and a standalone-only test would report "browser tab" forever.
+		 * @returns the probe for this device.
+		 */
+		function appBadgeEnv() {
+			const nav = typeof navigator === "object" && navigator !== null ? navigator : {};
+			let installed = nav.standalone === true;
+			if (!installed && typeof window !== "undefined" && typeof window.matchMedia === "function") {
+				for (const mode of APP_DISPLAY_MODES) {
+					try {
+						if (window.matchMedia(`(display-mode: ${mode})`).matches === true) { installed = true; break; }
+					} catch {}
+				}
+			}
+			return badgeCapabilityProbe({
+				secure: typeof window !== "undefined" && window.isSecureContext === true,
+				hasApi: typeof nav.setAppBadge === "function" && typeof nav.clearAppBadge === "function",
+				installed
+			});
+		}
+
+		/**
+		 * What the OS badge should say for a given count.
+		 *
+		 * The number is handed over AS IS (no `99+` clamping here): the system
+		 * saturates it in its own way, and duplicating that rule is how the two
+		 * projections start disagreeing. Switching the feature off clears the
+		 * badge rather than abandoning it — a number left behind after "off"
+		 * reads as a bug.
+		 * @param count - the unread count, i.e. the number the page badge shows.
+		 * @param enabled - the `appBadge` setting; only `true` enables it.
+		 * @returns `{ kind: "set", value }` or `{ kind: "clear" }`.
+		 */
+		function appBadgeEffect(count, enabled) {
+			const value = enabled === true ? normalizeCount(count) : 0;
+			return value > 0 ? { kind: "set", value } : { kind: "clear" };
+		}
+
+		/**
+		 * Which self-check line the settings page shows for this device.
+		 *
+		 * A missing probe is NOT reported as "insecure": that message tells the
+		 * user to change how they reach the page, which would be chasing the
+		 * wrong thing. Only a real reading may claim that.
+		 * @param probe - a `badgeCapabilityProbe` result.
+		 * @returns a locale key.
+		 */
+		function appBadgeCapabilityKey(probe) {
+			if (probe === null || typeof probe !== "object") return "appBadgeProbeUnsupported";
+			const facts = badgeCapabilityProbe(probe);
+			if (facts.secure !== true) return "appBadgeProbeInsecure";
+			if (facts.hasApi !== true) return "appBadgeProbeUnsupported";
+			return facts.installed === true ? "appBadgeProbeInstalled" : "appBadgeProbeTab";
+		}
+
+		/** The last effect actually handed to the API, so a repeat is a no-op. */
+		let lastAppBadgeId = null;
+
+		/**
+		 * The ONE place that talks to the Badging API.
+		 *
+		 * Idempotence is required here, not polish: `notifyBadge` fires on every
+		 * badge change AND again from the DOM watchdog that re-asserts the tab
+		 * badge, and each call costs an IPC to the browser process plus a taskbar
+		 * repaint. Only a real change in the projected effect reaches the API.
+		 * @param effect - an `appBadgeEffect` result.
+		 * @param force - re-send even when the effect is unchanged. Used only by
+		 *   the low-frequency OS-badge watchdog, because Windows/Edge can replace a
+		 *   numeric badge with a notification dot after our call succeeded.
+		 */
+		function applyAppBadge(effect, force) {
+			const intent = effect !== null && typeof effect === "object" ? effect : {};
+			// Anything that is not a positive number is a clear, so a bogus effect
+			// can never hand the system a `setAppBadge(0)`.
+			const id = intent.kind === "set" && typeof intent.value === "number" && intent.value > 0 ? `set:${intent.value}` : "clear";
+			if (id === lastAppBadgeId && force !== true) return;
+			const nav = typeof navigator === "object" && navigator !== null ? navigator : null;
+			if (nav === null || typeof nav.setAppBadge !== "function" || typeof nav.clearAppBadge !== "function") return;
+			lastAppBadgeId = id;
+			try {
+				// Always a number, never the argument-less "flag" form: on WebKit a
+				// no-argument call can REMOVE a badge that is already showing.
+				const settled = id === "clear" ? nav.clearAppBadge() : nav.setAppBadge(intent.value);
+				if (settled !== null && typeof settled === "object" && typeof settled.catch === "function") {
+					settled.catch(() => {
+						// The API rejected: the browser did NOT apply this effect, so
+						// forget it and let the next reconcile/retry try again. Guard
+						// against a newer call having replaced the remembered effect.
+						if (lastAppBadgeId === id) lastAppBadgeId = null;
+					});
+				}
+			} catch {
+				// A synchronous throw means nothing was applied, so the next
+				// reconcile retries instead of remembering a phantom success.
+				lastAppBadgeId = null;
+			}
+		}
+
+		/**
+		 * Reconcile the OS badge with the page badge.
+		 *
+		 * Both inputs are the page's own: the number the favicon and the header
+		 * badge already show, and the rule the host persists. Called from
+		 * `emitUnreadConfig` (rule arrived / switch moved) and `notifyBadge`
+		 * (number moved) — together those cover every way the badge can change.
+		 * @param force - re-send even if the projected effect is unchanged.
+		 */
+		function reconcileAppBadge(force) {
+			applyAppBadge(appBadgeEffect(effectiveCount(), unreadConfig.appBadge === true), force === true);
+		}
+
+		/**
+		 * Keep a positive numeric badge asserted while the app window is alive.
+		 *
+		 * Windows/Edge can render a notification glyph (a dot) over the numeric
+		 * badge after we set it; unlike the favicon, the OS badge then has no
+		 * watcher to put the number back. Re-send only when the plugin's own
+		 * projection says there SHOULD be a number, and never when it says clear —
+		 * so a count of 0 is not repeatedly cleared and no phantom badge appears.
+		 */
+		function reassertAppBadge() {
+			if (unreadConfig.appBadge !== true) return;
+			if (normalizeCount(effectiveCount()) <= 0) return;
+			reconcileAppBadge(true);
+		}
+
 		//#endregion
 		//#region favicon compositing
 		// The browser accepts exactly ONE image per <link rel="icon">, so a tab
@@ -1258,20 +1435,26 @@ window.__ModuleLoader__.load({
 			const currentIds = currentSessionIds(list);
 			const items = collectUnread(list, pending, config, seenState.seen);
 			const count = items.length;
-			// Being in a session is what marks it read — but only once you have STAYED
-			// `clearDelaySec` seconds (0 = the moment you enter, the original
-			// behaviour). A clock is torn down whenever you leave, or whenever that
-			// session becomes unread again from a fresh ending, so the clock restarts;
-			// that teardown IS the "continuous stay, leaving resets it" rule. A reload
-			// restarts it too, since the timers only live in this page.
+			// Being in a session is what marks it read — and the clock that does it is
+			// armed by ENTERING the session, never by a new ending.
+			//
+			// `clearDelaySec` still means "stay this long before the ending counts as
+			// seen" (0 = the moment you enter). What is new in 0.11.1 is WHEN the clock
+			// takes its snapshot: the moment the session joins the view. An ending that
+			// lands while you are already sitting there is therefore none of this
+			// clock's business — it stays unread until you leave and come back. The
+			// previous version re-armed on every new ending and chased the newest one,
+			// so a turn that finished while you watched was auto-read `clearDelaySec`
+			// seconds later: the dot for the session in front of you was a flash
+			// nobody could catch. See docs/adr/0006-entry-bounded-stay-clock.md.
+			//
+			// Leaving tears the clock down, which is what makes the stay "continuous".
+			// A reload restarts it too, since the timers only live in this page.
 			//
 			// One clock per session the main view shows: with two retained sessions,
 			// marking only the first left the session you were reading unread forever.
-			const unreadIds = new Set(items.map((item) => item.id));
-			const staySignature = currentIds
-				.filter((id) => unreadIds.has(id))
-				.map((id) => stayKeyFor(id, list))
-				.join("|");
+			const stayIds = currentIds.slice().sort();
+			const staySignature = stayIds.join("|");
 			const delayMs = config.clearDelaySec * 1000;
 			const [, bumpStay] = React.useState(0);
 			// The panel can move the marks without going through this component
@@ -1279,35 +1462,40 @@ window.__ModuleLoader__.load({
 			// badge all follow immediately.
 			const [, bumpPoke] = React.useState(0);
 			React.useEffect(() => subscribeUnreadPoke(() => bumpPoke((n) => n + 1)), []);
-			// The timer chain below is keyed on the signature, but every attempt reads
-			// the CURRENT list and marks; a ref is how the chain sees them.
+			// The effect below is keyed on the signature, but the snapshot it marks is
+			// taken from the CURRENT list; a ref is how it sees that list.
 			const stayLive = React.useRef({ list });
 			stayLive.current = { list };
+			/**
+			 * 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.
+			 */
+			const stayArmed = React.useRef(new Map());
 			React.useEffect(() => {
+				const snapshot = stayLive.current.list !== null && typeof stayLive.current.list === "object" && stayLive.current.list.byId !== null && typeof stayLive.current.list.byId === "object" ? stayLive.current.list.byId : {};
+				const live = new Set(stayIds);
+				for (const id of Array.from(stayArmed.current.keys())) {
+					if (!live.has(id)) stayArmed.current.delete(id);
+				}
+				for (const id of stayIds) {
+					if (!stayArmed.current.has(id)) stayArmed.current.set(id, lastTurnEndAt(snapshot[id]));
+				}
 				if (staySignature === "") return undefined;
-				const ids = staySignature.split("|").map((key) => key.slice(0, key.indexOf("\u0000")));
+				const armed = stayIds.map((id) => ({ id, endAt: stayArmed.current.get(id) }));
 				let cancelled = false;
 				let timer = 0;
+				// Single-shot on purpose: the snapshot is fixed, so there is nothing to
+				// chase. A newer ending found here belongs to the NEXT entry.
 				const attempt = () => {
 					if (cancelled) return;
-					const byId = stayLive.current.list !== null && typeof stayLive.current.list === "object" && stayLive.current.list.byId !== null && typeof stayLive.current.list.byId === "object" ? stayLive.current.list.byId : {};
 					let changed = false;
-					let stillUnread = false;
-					for (const id of ids) {
-						const endAt = lastTurnEndAt(byId[id]);
-						if (endAt <= 0) continue;
-						const seenAt = seenState.seen[id];
-						if (typeof seenAt === "number" && endAt <= seenAt) continue;
-						stillUnread = true;
-						if (noteSeen(id, endAt)) changed = true;
+					for (const target of armed) {
+						if (typeof target.endAt !== "number" || target.endAt <= 0) continue;
+						if (noteSeen(target.id, target.endAt)) changed = true;
 					}
 					if (changed) { saveSeenState(); bumpStay((n) => n + 1); }
-					// Watchdog. With the mark in the Host's own domain it should always
-					// land, so this normally stops after the first attempt; it exists for
-					// the case the mark DID land and the item is still unread (a fresh
-					// ending raced the timer), instead of leaving the dot red for good.
-					// A "waiting for you" item has no turn end to acknowledge: stop there.
-					timer = stillUnread ? window.setTimeout(attempt, 2000) : 0;
 				};
 				if (delayMs <= 0) attempt();
 				else timer = window.setTimeout(attempt, delayMs);
@@ -1776,6 +1964,9 @@ window.__ModuleLoader__.load({
 			const [badgeSourceValue, setBadgeSourceValue] = React.useState(badgeSource);
 			const [unread, setUnread] = React.useState(unreadConfig);
 			React.useEffect(() => subscribeUnreadConfig(setUnread), []);
+			// Sampled when the section mounts, which is the moment the user is
+			// looking at it. It reports local facts only (see badgeCapabilityProbe).
+			const [appBadgeProbe] = React.useState(() => appBadgeEnv());
 			// Draft text for the delay box: typing must not save on every keystroke,
 			// and the box has to show the CLAMPED value once the save lands (type
 			// 99999 and it settles on the 600 cap instead of lying about it).
@@ -1846,7 +2037,7 @@ window.__ModuleLoader__.load({
 				const next = normalizeUnreadConfig({ ...unreadConfig, ...patch });
 				emitUnreadConfig(next);
 				rpc.call("/api", "iconCustom/setUnreadRule", {
-					args: { request: { reasons: next.reasons, pending: next.pending, workspaceDot: next.workspaceDot, clearDelaySec: next.clearDelaySec } }
+					args: { request: { reasons: next.reasons, pending: next.pending, workspaceDot: next.workspaceDot, appBadge: next.appBadge, clearDelaySec: next.clearDelaySec } }
 				}).catch(() => {});
 			}, [rpc]);
 			// Toggle one unread reason. Applies locally at once; the host keeps the
@@ -1861,6 +2052,11 @@ window.__ModuleLoader__.load({
 			const onWorkspaceDotToggle = React.useCallback((checked) => {
 				saveUnreadRule({ workspaceDot: checked });
 			}, [saveUnreadRule]);
+			// The system-icon projection of the same number. Saved through the same
+			// one save path, so this field can never be dropped by a caller.
+			const onAppBadgeToggle = React.useCallback((checked) => {
+				saveUnreadRule({ appBadge: checked });
+			}, [saveUnreadRule]);
 			// Seconds you must stay in a session before it counts as read; 0 = as soon
 			// as you enter. Clamped by the shared normalizer, so a stray keystroke can
 			// never persist an absurd delay.
@@ -2129,6 +2325,20 @@ window.__ModuleLoader__.load({
 						),
 						React.createElement("div", { style: style.hint }, t("workspaceDotHint"))
 					),
+					React.createElement("div", { style: { marginTop: "10px" } },
+						React.createElement("label", { style: { display: "inline-flex", alignItems: "center", gap: "6px", fontSize: 12, color: "var(--dsw-alias-label-primary)", cursor: "pointer" } },
+							React.createElement("input", {
+								type: "checkbox",
+								checked: unread.appBadge !== false,
+								onChange: (event) => onAppBadgeToggle(event.target.checked === true)
+							}),
+							React.createElement("span", null, t("appBadgeLabel"))
+						),
+						React.createElement("div", { style: style.hint }, t("appBadgeHint")),
+						// What THIS device is — never a claim about the platform.
+						React.createElement("div", { style: style.hint }, t(appBadgeCapabilityKey(appBadgeProbe))),
+						React.createElement("div", { style: style.hint }, t("appBadgeFootnote"))
+					),
 					React.createElement("div", { style: style.hint }, t("badgeTestHint"))
 				),
 				notice ? React.createElement("div", { style: style.notice }, notice) : null,
@@ -2271,7 +2481,10 @@ window.__ModuleLoader__.load({
 				observer.observe(document.head, { childList: true, subtree: true, attributes: true, attributeFilter: ["href", "rel"] });
 				window.addEventListener("visibilitychange", schedule);
 				window.addEventListener("focus", schedule);
-				const interval = window.setInterval(reconcileFavicon, 5000);
+				const interval = window.setInterval(() => {
+					reconcileFavicon();
+					reassertAppBadge();
+				}, 5000);
 				return () => {
 					observer.disconnect();
 					window.removeEventListener("visibilitychange", schedule);

package/lib/index.js

@@ -459,7 +459,7 @@ export class FaviconCustomService extends TypertRemoteService {
 	 * icon RPCs (`getStatus` / `setIcon` / `setPwa` / `setLogo` / `resetIcon`)
 	 * keep their EXACT pre-badge response shape, so a problem in this feature
 	 * can never break the icon itself.
-	 * @returns `{ reasons, pending, workspaceDot, clearDelaySec, hostNow }`.
+	 * @returns `{ reasons, pending, workspaceDot, appBadge, clearDelaySec, hostNow }`.
 	 */
 	async getUnreadRule() {
 		return this._unreadRuleView()
@@ -469,7 +469,7 @@ export class FaviconCustomService extends TypertRemoteService {
 	 * typert endpoint: replace the unread-badge rule — which turn-end reasons
 	 * light the badge. The rule is applied on the client, so this takes effect
 	 * without re-folding any session log.
-	 * @param request - `{ reasons, pending?, workspaceDot?, clearDelaySec? }`; unknown or missing keys fall back to defaults.
+	 * @param request - `{ reasons, pending?, workspaceDot?, appBadge?, clearDelaySec? }`; unknown or missing keys fall back to defaults.
 	 * @returns the stored rule.
 	 */
 	async setUnreadRule(request) {
@@ -496,6 +496,7 @@ export class FaviconCustomService extends TypertRemoteService {
 			reasons: this.unread.reasons,
 			pending: this.unread.pending,
 			workspaceDot: this.unread.workspaceDot,
+			appBadge: this.unread.appBadge,
 			clearDelaySec: this.unread.clearDelaySec,
 			hostNow: Date.now()
 		}

package/lib/typert.host.js

@@ -53,6 +53,8 @@ const unreadRuleSchema = z.object({
 	pending: z.boolean(),
 	/** 实验项:工作区图标上的红点(贴产品 DOM,可一键关闭)。 */
 	workspaceDot: z.boolean(),
+	/** 在系统应用图标上显示角标(安装为应用后生效);只决定"设几/清空",样子由系统决定。 */
+	appBadge: z.boolean(),
 	/** 进入会话后要连续待满多少秒才算"看过";0 = 进入即已读。上限 10 分钟。 */
 	clearDelaySec: z.number().int().nonnegative().max(600),
 	/**
@@ -67,6 +69,7 @@ const setUnreadRuleRequestSchema = z.object({
 	reasons: z.record(z.string(), z.boolean()),
 	pending: z.boolean().optional(),
 	workspaceDot: z.boolean().optional(),
+	appBadge: z.boolean().optional(),
 	clearDelaySec: z.number().int().nonnegative().max(600).optional()
 })
 
@@ -278,7 +281,7 @@ export const TYPERT = {
 					{
 						kind: 'method',
 						name: 'getUnreadRule',
-						signature: 'async getUnreadRule(): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; clearDelaySec: number; hostNow: number }>',
+						signature: 'async getUnreadRule(): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; appBadge: boolean; clearDelaySec: number; hostNow: number }>',
 						description: "Read the unread-badge rule.",
 						summary: "Read the unread-badge rule.",
 						jsDoc: "/** Read the unread-badge rule. */",
@@ -287,7 +290,7 @@ export const TYPERT = {
 					{
 						kind: 'method',
 						name: 'setUnreadRule',
-						signature: 'async setUnreadRule(request: { reasons: Record<string, boolean>; pending?: boolean; workspaceDot?: boolean; clearDelaySec?: number }): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; clearDelaySec: number; hostNow: number }>',
+						signature: 'async setUnreadRule(request: { reasons: Record<string, boolean>; pending?: boolean; workspaceDot?: boolean; appBadge?: boolean; clearDelaySec?: number }): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; appBadge: boolean; clearDelaySec: number; hostNow: number }>',
 						description: "Replace the unread-badge rule: which turn-end reasons light the red dot.",
 						summary: "Set the unread-badge rule.",
 						jsDoc: "/** Set the unread-badge rule. */",

package/lib/unread.js

@@ -52,6 +52,16 @@ export const UNREAD_PENDING_DEFAULT = true
  */
 export const UNREAD_WORKSPACE_DOT_DEFAULT = true
 
+/**
+ * 默认:在系统应用图标上显示角标(安装为应用后生效)。
+ *
+ * 它只是"同一个数字在系统图标上的投影",所以默认跟随红点一起打开;
+ * 关掉它等于"不要这个投影",而不等于"这个功能不存在"。
+ * 注意:**探测到 API ≠ 角标会出现**(安卓与 Linux 上方法存在但静默无效,
+ * iOS 上还额外要求通知权限),详见 docs/adr/0005-app-icon-badge.md。
+ */
+export const UNREAD_APP_BADGE_DEFAULT = true
+
 /**
  * 默认:进入会话即视为已读(0 秒)。
  * 大于 0 时,你必须在那个会话里**连续**待满这么多秒它才算"看过";中途切走会
@@ -87,8 +97,8 @@ export function normalizeReasons(input) {
 
 /**
  * 把任意输入夹成完整设置。
- * @param input - `{ reasons?, pending?, workspaceDot?, clearDelaySec? }`,可以是脏的、缺项的、null
- * @returns `{ reasons, pending, workspaceDot, clearDelaySec }` —— 每一项都完整
+ * @param input - `{ reasons?, pending?, workspaceDot?, appBadge?, clearDelaySec? }`,可以是脏的、缺项的、null
+ * @returns `{ reasons, pending, workspaceDot, appBadge, clearDelaySec }` —— 每一项都完整
  */
 export function normalizeUnreadConfig(input) {
 	const source = input !== null && typeof input === 'object' ? input : {}
@@ -96,6 +106,7 @@ export function normalizeUnreadConfig(input) {
 		reasons: normalizeReasons(source.reasons),
 		pending: typeof source.pending === 'boolean' ? source.pending : UNREAD_PENDING_DEFAULT,
 		workspaceDot: typeof source.workspaceDot === 'boolean' ? source.workspaceDot : UNREAD_WORKSPACE_DOT_DEFAULT,
+		appBadge: typeof source.appBadge === 'boolean' ? source.appBadge : UNREAD_APP_BADGE_DEFAULT,
 		clearDelaySec: normalizeClearDelay(source.clearDelaySec)
 	}
 }

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@cowwo/dsh-icon-custom",
-  "version": "0.10.2",
-  "description": "自定义浏览器标签页图标:在设置页上传 SVG/PNG/ICO,立即生效并持久保存,自动适配安卓/iOS/平板 PWA 图标。· Custom browser tab favicon: upload SVG/PNG/ICO from the settings page, applies instantly and persists, auto-sizes PWA icons for Android/iOS/tablets.",
+  "version": "0.11.1",
+  "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",
   "license": "MIT",
+  "scripts": {
+    "test": "node test/app-badge.mjs && node test/unread-panel.mjs && node test/unread-clear.mjs"
+  },
   "dependencies": {
     "jimp": "^1.6.1",
     "zod": "^4.4.3"