@cowwo/dsh-icon-custom 0.11.1 → 0.15.0

package/README.md

@@ -88,6 +88,8 @@ The uploaded file is stored verbatim (never re‑encoded) so the favicon keeps i
 
 Icons are stored per‑user under `$DSH_HOME/custom-favicon/`. "Reset" only clears the active marker; stored files are kept for a future icon‑library UI.
 
+That directory also holds two JSON files: `unread.json` (which turn-end reasons count as unread) and `unread-seen.json` (the seen watermark, `{ version, seen: { sessionId → endAt } }`, capped at 400 entries and written temp-then-rename). Both are **disposable**: deleting the first restores the default rule, deleting the second makes each browser re-baseline at "the last time it was open" (which does not resurrect old dots). The watermark is host-owned on purpose — looked at on any device means read on every device — while each browser keeps its own copy as a cache and offline queue.
+
 ## License
 
 MIT

package/README.zh.md

@@ -58,13 +58,13 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
 规则:
 
 - 数字 = **几个会话**在等你(不是几件事);同一个会话只占一格。
-- 只有子代理会话不计。**你正开着的那个会话也算**——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分;**要清掉它,切走再切回来即可**(你人已经在里面时又结束的那一轮不会自动消,见下一条)。
-- **已读记在每个浏览器自己身上**(localStorage):进过 = 处理过,刷新/重启不会"复活";装插件之前的历史结束也不算。
+- 只有子代理会话不计。**什么算"你在看"**(0.12.1 起):那个会话必须真的显示在主区域的对话里(切到「插件 / 设置」这类页面不算)、浏览器标签页在前台(切到别的标签页或最小化不算)、且屏幕上就是它——残留的"最近打开过"不再算数。**你正开着的那个会话也算**;**要清掉它,切走再切回来即可**(你人已经在里面时又结束的那一轮不会自动消,见下一条)。
+- **已读记在宿主**(`$DSH_HOME/custom-favicon/unread-seen.json`):进过 = 处理过,刷新/重启不会"复活",**任何一台设备上看过,所有设备都不再提醒**(开着的页面最多约一分钟收敛,刷新则立刻)。浏览器自己也留一份,但只当缓存兼离线队列——所以清站点数据、换浏览器、无痕窗口都不会把"已读"丢回去。装插件之前的历史结束也不算。
 - **可以要求"待够才算已读"**:设置页填一个秒数(默认 0)。填 0 = 进去就算已读(红点立即消失);填 N = 你要在那个会话里**连续待满 N 秒**它才算看过,中途切走就清零重数,刷新页面也重新数。上限 600 秒。
   **计时只认"你进入会话时已经存在的那次结束"**:你人已经在会话里的时候它又跑完一轮,那一轮**不算数**——红点会一直亮着,等你**切走再进来**才消。这样"我正看着的会话跑完了"这件事不会被几秒钟后自动抹掉(0.11.1 起;此前是"停留满 N 秒就把最新那次结束也标成已读",红点只闪一下)。
 - 数据全部来自官方:`turn/end` 事件经官方 session projection 折叠,加上官方的"等待交互"注册表——**不依赖任何其他插件**。
 - 设置页的**数据来源**可以切到"手动测试",手填数字试看效果。
-- **工作区和会话行上的红点(实验)**:侧栏每个**工作区**那一行的文件夹图标右上角一个小红点,每个**有未读的会话**在标题右边跟一个小红点——一眼看出"事情在哪个工作区的哪个会话"。这一项是**贴着页面结构**做的——DSH 大版本升级后**可能失效**,失效时只会变成"不显示",**不影响**红点数字、清单和跳转;设置页里有一个开关可以随时关掉它。
+- **工作区和会话行上的红点(实验)**:侧栏每个**工作区**那一行的文件夹图标右上角一个小红点(收起的工作区里有多少未读,就看它),每个**有未读的会话**在标题右边跟一个小红点——一眼看出"事情在哪个工作区的哪个会话"。定位走 DSH 自己的 `data-row-key`(工作区、会话都按 **id**,不靠标题文字):标题重复不会串行,**折叠起来的会话不单独画点**——它的行没有渲染,由工作区那一行的点和「待处理」清单代表它。这一项是**贴着页面结构**做的——DSH 大版本升级后**可能失效**,失效时只会变成"不显示",**不影响**红点数字、清单和跳转;设置页里有一个开关可以随时关掉它。
 - **想知道具体是哪个会话?** 侧栏「工作区」标题的**右上角**有一个**红底数字**(没有待处理时是灰色 0,位置不变);点开是待处理会话清单,**按工作区分组**(工作区名 · 会话名 · 在等你/刚结束),点其中一条**直接跳到那个会话**。
 
 ## 应用图标角标(系统图标上的红点)
@@ -112,6 +112,8 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
 
 图标按用户保存在 `$DSH_HOME/custom-favicon/`。**恢复默认**只清除当前生效标记,已保存的文件会保留,为将来的图标库 UI 做准备。
 
+同一个目录里还有两份 JSON:`unread.json`(哪些结束原因算未读)与 `unread-seen.json`(已读水位线,`{ version, seen: { 会话id → endAt } }`,上限 400 条、写入是 temp+rename)。两份都是**可丢的**:删掉 `unread.json` 回到默认规则,删掉 `unread-seen.json` 则每台浏览器按"上次在线时间"重新起基线(不会把历史红点全部点亮)。
+
 ## 许可证
 
 MIT

package/client/client.js

@@ -69,7 +69,7 @@ window.__ModuleLoader__.load({
 			ageMonths: "{n}个月",
 			ageYears: "{n}年",
 			workspaceDotLabel: "在工作区和会话行上显示红点(实验)",
-			workspaceDotHint: "在侧栏工作区那一行的文件夹图标上点一个小红点。这一项是贴着页面结构做的,DSH 升级后可能失效;失效时只会变成\"不显示\",不会影响红点数字、清单、跳转这些功能,随时可以关掉它。",
+			workspaceDotHint: "在侧栏工作区那一行的文件夹图标上点一个小红点(收起的工作区里有多少未读,就看它),有未读的会话在其标题右边也跟一个小红点。会话行上的点只在那一行真的显示着时才画:折叠起来的会话由工作区那一行的点和「待处理」清单代表。这一项是贴着页面结构做的,DSH 升级后可能失效;失效时只会变成\"不显示\",不会影响红点数字、清单、跳转这些功能,随时可以关掉它。",
 			appBadgeLabel: "在系统应用图标上显示红点",
 			appBadgeHint: "安装为应用后,把同一个数字也放到系统图标上:Windows 是任务栏图标上的角标,macOS 是 Dock 角标,iOS 是主屏图标上的数字。样子由系统决定——Windows 上 Chrome 画深色圆+白字,Edge 走 Windows 系统徽章通道(是否显示数字由 Edge/Windows 决定);插件会周期重设数字,但只在应用窗口开着时更新。",
 			appBadgeFootnote: "角标只在应用窗口开着时由本插件更新;数字超过 99 时由系统显示为 99+。",
@@ -80,7 +80,7 @@ window.__ModuleLoader__.load({
 			badgeTestHint: "真实未读 = 有会话发生了上面勾选的情况、而且你还没看过它(打开该会话即视为已读)。你正开着的会话也算——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分。只有子代理不计。手动模式:自己填数字试看效果。刷新页面后回到真实未读。",
 			clearDelayLabel: "进入会话后多久算已读:",
 			clearDelayUnit: "秒",
-			clearDelayHint: "填 0 = 进去就算已读(红点立即消失)。大于 0 时,你要在那个会话里连续待满这么多秒它才算看过:中途切走会清零重数,刷新页面也重新数。**计时只认\"你进入会话时已经存在的结束\"**——你人已经在里面的时候又跑完一轮,那一轮不算数:它会一直亮着,等你切走再进来才会清。上限 600 秒。"
+			clearDelayHint: "填 0 = 进去就算已读(红点立即消失)。大于 0 时,你要在那个会话里连续待满这么多秒它才算看过:中途切走会清零重数,刷新页面也重新数。**计时只认\"你进入会话时已经存在的结束\"**——你人已经在里面的时候又跑完一轮,那一轮不算数:它会一直亮着,等你切走再进来才会清。上限 600 秒。**只有它真的显示在屏幕上、且标签页在前台时才算看过**:切到「插件/设置」页或把标签页切到后台都不算。已读记在宿主($DSH_HOME/custom-favicon/unread-seen.json):任何一台设备上看过,所有设备都不再提醒;浏览器那份只是缓存,清站点数据不会把已读丢回去。"
 		};
 		const en = {
 			nav: "Favicon",
@@ -142,7 +142,7 @@ window.__ModuleLoader__.load({
 			ageMonths: "{n}mo",
 			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.",
+			workspaceDotHint: "Adds a small red dot to the folder icon of each workspace row (a collapsed workspace shows how many of its sessions are unread there), and one beside the title of every unread session row. A session dot is only drawn while that row is really rendered: folded sessions are represented by their workspace row's dot and the pending panel. 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+.",
@@ -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."
+			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."
 		};
 		//#endregion
 
@@ -309,7 +309,7 @@ window.__ModuleLoader__.load({
 		}
 
 		/**
-		 * The seen watermark lives in the HOST's clock domain.
+		 * The seen watermark: the HOST owns it, this browser keeps the working copy.
 		 *
 		 * A turn end arrives stamped with the Host's `turn/end.time`; a mark written
 		 * from the browser's `Date.now()` only lines up while both clocks agree. A
@@ -318,11 +318,26 @@ window.__ModuleLoader__.load({
 		 * all — the one failure users report as "点进去也不消". Marks now store the
 		 * `endAt` they acknowledge, and `lastActiveAt` stores a host-domain time, so
 		 * every comparison in `collectUnread` stays inside one clock.
+		 *
+		 * Since 0.11.2 the authoritative table lives in the Host
+		 * (`~/.dsh/custom-favicon/unread-seen.json`, merged max-per-session). This
+		 * copy is what the badge reads — so the page never waits for a round trip and
+		 * keeps working offline — and doubles as the pending queue: every local mark
+		 * is pushed back on the next sync, and a merge can only move marks forward.
+		 * That is what makes "looked at it" survive a cleared browser profile and mean
+		 * the same thing on every device.
 		 */
 		const SEEN_STORE_KEY = "dsh-icon-custom.unread-seen.v2";
 		/** 0.10.1 and earlier wrote browser timestamps here; migrated once. */
 		const LEGACY_SEEN_STORE_KEY = "dsh-icon-custom.unread-seen.v1";
+		/** Mirror of the Host's cap (see lib/unread.js). */
 		const SEEN_MAX = 400;
+		/** Coalescing window for watermark pushes: one small RPC per burst, not per session. */
+		const HOST_SYNC_DEBOUNCE_MS = 2000;
+		/** Retry gap after a failed push (offline, or a Host without the endpoint). */
+		const HOST_SYNC_RETRY_MS = 30000;
+		/** Ceiling for that retry gap: an old Host must not be probed forever every 20 s. */
+		const HOST_SYNC_MAX_RETRY_MS = 300000;
 		/** Host clock minus browser clock, from the last Host sample; null until known. */
 		let hostClockOffset = null;
 		/** This browser's clock expressed in the Host's domain (best effort). */
@@ -347,10 +362,140 @@ window.__ModuleLoader__.load({
 		const seenState = loadSeenState();
 		/** When this browser last had the app open before this page load (host domain). */
 		const seenBootAt = seenState.lastActiveAt > 0 ? seenState.lastActiveAt : 0;
+		/** The connection RPC, once `apply` has one; null keeps every push a no-op. */
+		let seenRpc = null;
+		/** Whether this page load has already converged with the Host once. */
+		let hostSyncedOnce = false;
+		/** Whether local marks changed since the last successful push. */
+		let hostDirty = false;
+		let hostSyncTimer = 0;
+		let hostRetryTimer = 0;
+		let hostSyncInFlight = false;
+		/** Escalating gap between failed pushes; any success resets it. */
+		let hostRetryDelay = HOST_SYNC_RETRY_MS;
+		/** No push is attempted before this moment (the backoff window). */
+		let hostBackoffUntil = 0;
+		/** Whether the current failure streak has been reported (warn once per streak). */
+		let hostSyncWarned = false;
+		/**
+		 * Push the local table soon, unless there is nothing to say.
+		 *
+		 * Called from `saveSeenState`, which is also the 20-second "this browser is
+		 * still here" touch: that touch must NOT count as a change, or the table would
+		 * travel every 20 seconds. `hostSyncedOnce` covers the first push of a page
+		 * load, which is also the migration (local-only marks going up) and the
+		 * self-heal (a lost Host file coming back from this browser).
+		 * @param delayMs - override the coalescing window; non-positive uses the default.
+		 */
+		function scheduleHostSync(delayMs) {
+			if (seenRpc === null || hostSyncInFlight) return;
+			if (!hostDirty && hostSyncedOnce) return;
+			if (hostSyncTimer !== 0) return;
+			// A failed push escalates its own retry; the 20-second touch must not keep
+			// poking a Host that has no such endpoint (an older DSH, or offline).
+			if (Date.now() < hostBackoffUntil) return;
+			const wait = typeof delayMs === "number" && delayMs > 0 ? delayMs : HOST_SYNC_DEBOUNCE_MS;
+			hostSyncTimer = window.setTimeout(() => { hostSyncTimer = 0; flushHostSeen(); }, wait);
+		}
+		/**
+		 * Adopt the Host's table: per session the NEWER of the two wins.
+		 *
+		 * Max-merge (never overwrite) is what makes both directions safe: the Host file
+		 * lost or truncated → this browser's copy wins; this browser's localStorage
+		 * cleared → the Host's copy wins. It is also the whole migration path.
+		 * @param seen - the Host's table (`id → endAt`), or anything.
+		 * @returns whether the local table gained anything.
+		 */
+		function adoptHostSeen(seen) {
+			if (seen === null || typeof seen !== "object") return false;
+			let gained = false;
+			for (const id of Object.keys(seen)) {
+				if (typeof id !== "string" || id === "") continue;
+				const at = seen[id];
+				if (typeof at !== "number" || !Number.isFinite(at) || at <= 0) continue;
+				const previous = seenState.seen[id];
+				if (typeof previous === "number" && previous >= at) continue;
+				seenState.seen[id] = at;
+				gained = true;
+			}
+			return gained;
+		}
+		/**
+		 * Send the whole local table and adopt the merged answer.
+		 *
+		 * Whole-table, not a delta: the payload is a few KB, the Host merges by max (so
+		 * a duplicate or partial round trip is harmless), and any lost message heals on
+		 * the next one. A failure keeps the marks here — they are already in
+		 * localStorage and the badge reads them — and retries later.
+		 */
+		function flushHostSeen() {
+			if (seenRpc === null || hostSyncInFlight) return;
+			if (!hostDirty && hostSyncedOnce) return;
+			hostSyncInFlight = true;
+			const marks = { ...seenState.seen };
+			let pending;
+			try {
+				// Args are nested under the descriptor's parameter name ("request"), which
+				// is what the gateway checks: a flat `{ marks }` is rejected with
+				// `gateway/arguments-invalid` before the method ever runs.
+				pending = seenRpc.call("/api", "iconCustom/setUnreadSeen", { args: { request: { marks } } });
+			} catch (error) {
+				// A carrier that throws synchronously must not wedge the in-flight guard:
+				// that would stop every later push for the life of the page, silently.
+				hostSyncInFlight = false;
+				noteHostSyncFailure(error);
+				return;
+			}
+			Promise.resolve(pending).then(
+				(resp) => {
+					hostSyncInFlight = false;
+					if (resp === null || typeof resp !== "object" || resp.ok !== true) {
+						const reason = resp !== null && typeof resp === "object" && resp.error !== undefined ? JSON.stringify(resp.error) : "resp.ok !== true";
+						noteHostSyncFailure(new Error("setUnreadSeen 被拒绝: " + reason));
+						return;
+					}
+					const value = resp.value !== null && typeof resp.value === "object" ? resp.value : {};
+					const gained = adoptHostSeen(value.seen);
+					hostSyncedOnce = true;
+					hostRetryDelay = HOST_SYNC_RETRY_MS;
+					hostBackoffUntil = 0;
+					hostSyncWarned = false;
+					// The Host knew marks this browser did not: keep them and push the union
+					// once more. The next answer cannot gain anything, so this terminates.
+					// Repaint too: the badge, the row dots and the panel all read this
+					// browser's copy, and nothing else would re-render for a mark that
+					// arrived over the wire.
+					hostDirty = gained;
+					if (gained) { saveSeenState(); emitUnreadPoke(); scheduleHostSync(); }
+				},
+				(error) => { hostSyncInFlight = false; noteHostSyncFailure(error); }
+			);
+		}
+		/**
+		 * One failed push: report it once per streak, then back off and try again later.
+		 *
+		 * Reported (not swallowed) because a watermark that cannot reach the Host is a
+		 * silent, confusing failure — "为什么另一台设备还亮着" — and there is nothing on
+		 * screen to explain it. The badge itself keeps working from the local copy, so
+		 * this must never look fatal, and it warns once rather than on every retry.
+		 * @param error - whatever the carrier rejected with.
+		 */
+		function noteHostSyncFailure(error) {
+			if (!hostSyncWarned) {
+				hostSyncWarned = true;
+				try { console.warn("dsh-icon-custom: 已读水位线同步到宿主失败(红点仍照常工作,会自动重试):", (error && error.message) || error); } catch {}
+			}
+			const wait = hostRetryDelay;
+			hostRetryDelay = Math.min(hostRetryDelay * 2, HOST_SYNC_MAX_RETRY_MS);
+			hostBackoffUntil = Date.now() + wait;
+			if (hostRetryTimer !== 0) window.clearTimeout(hostRetryTimer);
+			hostRetryTimer = window.setTimeout(() => { hostRetryTimer = 0; flushHostSeen(); }, wait);
+		}
 		function saveSeenState() {
 			try {
 				window.localStorage.setItem(SEEN_STORE_KEY, JSON.stringify({ domain: "host", lastActiveAt: seenState.lastActiveAt, seen: seenState.seen }));
 			} catch {}
+			scheduleHostSync();
 		}
 		/**
 		 * Learn the Host↔browser clock offset from a Host timestamp, and fold a
@@ -390,12 +535,20 @@ window.__ModuleLoader__.load({
 			const previous = seenState.seen[sessionId];
 			if (typeof previous === "number" && previous >= mark) return false;
 			seenState.seen[sessionId] = mark;
+			// Only a REAL mark counts as a change: the 20-second "still here" touch also
+			// lands in `saveSeenState`, and it must not drag the whole table to the Host.
+			hostDirty = true;
 			return true;
 		}
 		/**
 		 * First sight of a session is watermarked at the last time this browser was
 		 * here — so an ending that happened while the app was closed still counts as
 		 * unread, while endings from before the plugin was installed do not.
+		 *
+		 * Unchanged by the move to a Host-owned table: a session nobody has a mark for
+		 * still needs a starting value, and "the last time this browser was here" is
+		 * the honest one. A mark dropped by the Host's pruning simply re-baselines here
+		 * on the next load, which is why pruning cannot resurrect old dots.
 		 * @returns whether anything was learned (callers persist only then).
 		 */
 		function ensureSeenBaseline(ids) {
@@ -409,23 +562,62 @@ 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.
 		 *
-		 * 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.
+		 * 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.
 		 */
-		function currentSessionIds(list) {
+		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];
 			const byId = list.byId;
@@ -1004,22 +1196,32 @@ window.__ModuleLoader__.load({
 		/**
 		 * Roll the pending sessions up to one dot per workspace.
 		 *
-		 * Pure: `titles` maps sessionId → the workspace title the sidebar shows
-		 * (assembled from the official workspace snapshot); a session missing from it
-		 * falls back to the cwd basename `collectUnread` already carries.
-		 * @returns `[{ name, count }]`, busiest workspace first.
+		 * Pure: `owners` maps sessionId → `{ id, title }` from the official workspace
+		 * snapshot. Both halves matter downstream: the ID anchors the marker to the
+		 * row the browser itself keys (`data-row-key="workspace:<id>"`), which is what
+		 * makes the folder dot survive a Workspace whose displayed name differs from
+		 * the stored title, two Workspaces sharing one title, and a title that is
+		 * simply empty. The title stays for the tooltip; a session with neither falls
+		 * back to the cwd basename `collectUnread` already carries.
+		 * @returns `[{ id, name, count }]`, busiest workspace first.
 		 */
-		function dotsFromItems(items, titles) {
+		function dotsFromItems(items, owners) {
 			const counts = new Map();
 			for (const item of Array.isArray(items) ? items : []) {
 				if (item === null || typeof item !== "object") continue;
-				const mapped = titles !== null && typeof titles === "object" ? titles[item.id] : undefined;
-				const name = typeof mapped === "string" && mapped !== "" ? mapped : (typeof item.where === "string" ? item.where : "");
+				const owner = owners !== null && typeof owners === "object" ? owners[item.id] : undefined;
+				const title = owner !== null && typeof owner === "object" && typeof owner.title === "string" ? owner.title : "";
+				const name = title !== "" ? title : (typeof item.where === "string" ? item.where : "");
 				if (name === "") continue;
-				counts.set(name, (counts.get(name) || 0) + 1);
+				const id = owner !== null && typeof owner === "object" && typeof owner.id === "string" ? owner.id : "";
+				// One dot per Workspace: two Sessions of the same Workspace must not
+				// produce two entries that later paint on top of each other.
+				const key = id !== "" ? id : name;
+				const existing = counts.get(key);
+				if (existing === undefined) counts.set(key, { id, name, count: 1 });
+				else existing.count++;
 			}
-			return [...counts.entries()]
-				.map(([name, count]) => ({ name, count }))
+			return [...counts.values()]
 				.sort((a, b) => b.count - a.count || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 		}
 
@@ -1289,17 +1491,101 @@ window.__ModuleLoader__.load({
 		 * Where one session's marker goes: the tight title holder INSIDE that
 		 * session's own row. The row is found by `data-row-key`; the title inside it
 		 * is still matched by text, because that is the element the marker hangs off.
-		 * Falls back to the old whole-region title match on a build without row keys.
+		 *
+		 * A Session whose row is NOT in the DOM — folded behind "Show more", inside a
+		 * collapsed Workspace, or filtered out — gets NO marker. It used to fall back
+		 * to a whole-region title match, and that guess is exactly what puts a dot on
+		 * the wrong row: a DIFFERENT Session with the same title owns the only
+		 * rendered text node of that name, so the folded one's marker landed on the
+		 * visible one's row (two markers on one row, none on the real one). The
+		 * Workspace folder dot and the pending panel already speak for Sessions whose
+		 * rows are not rendered, so skipping loses no information.
+		 *
+		 * `legacyTitleMatch` is reserved for a build that stamps no row keys at all,
+		 * where the title is the only handle that exists.
+		 * @param legacyTitleMatch - whether this build predates `data-row-key`.
 		 * @returns `{ title, row }`, or null when this row cannot be trusted.
 		 */
-		function sessionRowTarget(container, id, title) {
+		function sessionRowTarget(container, id, title, legacyTitleMatch) {
 			const row = sessionRowElement(container, id);
 			if (row !== null) {
 				const inside = labelElementFor(row, title);
 				return inside === null ? null : titleTargetFor(inside, title);
 			}
+			if (legacyTitleMatch !== true) return null;
 			return titleTargetFor(labelElementFor(container, title), title);
 		}
+		/**
+		 * Whether the shipped browser stamps Session rows with `data-row-key`.
+		 *
+		 * Asked once per paint, not once per row: the strict path is only relaxed for
+		 * a build that has no row keys anywhere, never for one unlucky lookup.
+		 * @param container - the browsing region root (non-null).
+		 * @returns true when row keys are in use (and on any probe failure — the
+		 * strict path is the safe default).
+		 */
+		function sessionRowKeysInUse(container) {
+			try { return container.querySelector('[data-row-key^="session:"]') !== null; } catch { return true; }
+		}
+		/**
+		 * The DOM row of one Workspace, by the official row key, or null.
+		 *
+		 * Same handle as `sessionRowElement`, and the reason the folder dot no longer
+		 * depends on the displayed name: DSH renders a Workspace still carrying its
+		 * automatic title under a localized default name, and two Workspaces can share
+		 * one title, so a text match can miss or collide.
+		 * @param container - the browsing region root.
+		 * @param id - the Workspace id.
+		 * @returns the row element, or null.
+		 */
+		function workspaceRowElement(container, id) {
+			if (typeof id !== "string" || id === "") return null;
+			try { return container.querySelector(`[data-row-key="workspace:${id}"]`); } catch { return null; }
+		}
+		/**
+		 * The row box + folder icon a Workspace marker hangs off, from the keyed row.
+		 *
+		 * The key normally sits on the row itself; a build that stamps it on a group
+		 * wrapper fails the row-size check, so a bounded set of that wrapper's own rows
+		 * gets the same test before giving up. Either way the marker must land on a
+		 * row-sized box whose LEADING glyph is the folder — requiring a left-hand icon
+		 * is what keeps the dot off the end of the text.
+		 * @returns `{ row, icon }`, or null when this row cannot be trusted.
+		 */
+		function folderTargetFor(row) {
+			if (row === null || row === undefined) return null;
+			const candidates = [row];
+			try {
+				const inner = row.querySelectorAll("div");
+				for (let i = 0; i < inner.length && candidates.length < 12; i++) candidates.push(inner[i]);
+			} catch { /* the keyed element alone is still worth testing */ }
+			for (const candidate of candidates) {
+				const rect = candidate.getBoundingClientRect();
+				if (rect.height < WS_ROW_MIN_H || rect.height > WS_ROW_MAX_H || rect.width < WS_ROW_MIN_W) continue;
+				const icons = candidate.querySelectorAll("svg");
+				for (const icon of icons) {
+					const iconRect = icon.getBoundingClientRect();
+					if (iconRect.width <= 0 || iconRect.height <= 0) continue;
+					if (iconRect.left - rect.left > rect.width / 3) continue;
+					return { row: candidate, icon };
+				}
+			}
+			return null;
+		}
+		/**
+		 * The stable key a Workspace marker is stored under: its ID when known.
+		 *
+		 * The attribute value used to be the displayed title, which two Workspaces can
+		 * share — the reconcile pass would then treat one of them as a stranger and
+		 * remove a marker that is still wanted.
+		 * @param entry - one `{ id, name }` entry from `dotsFromItems`.
+		 * @returns the key, or undefined when the entry carries neither.
+		 */
+		function workspaceDotKey(entry) {
+			if (entry === null || typeof entry !== "object") return undefined;
+			if (typeof entry.id === "string" && entry.id !== "") return entry.id;
+			return entry.name;
+		}
 		function paintWorkspaceDots() {
 			if (workspaceDotGivenUp) return;
 			const enabled = unreadConfig.workspaceDot !== false;
@@ -1315,7 +1601,7 @@ window.__ModuleLoader__.load({
 				// Reconcile, never wipe-and-redraw: a marker that is already correct is
 				// left untouched, so one unlucky lookup (a re-render in flight, a name
 				// matched twice for a moment) can no longer blink an existing dot away.
-				const wantedNames = new Set(wanted.map((entry) => entry.name));
+				const wantedNames = new Set(wanted.map((entry) => workspaceDotKey(entry)));
 				const wantedIds = new Set(wantedRows.map((entry) => entry.id));
 				document.querySelectorAll("[" + WS_DOT_ATTR + "]").forEach((node) => {
 					if (!node.isConnected || !wantedNames.has(node.getAttribute(WS_DOT_ATTR))) node.remove();
@@ -1324,12 +1610,21 @@ window.__ModuleLoader__.load({
 					if (!node.isConnected || !wantedIds.has(node.getAttribute(ROW_DOT_ATTR))) node.remove();
 				});
 				if (container === null) { workspaceDotPainting = false; return; } // start-up race
+				const legacyTitleMatch = !sessionRowKeysInUse(container);
 				for (const entry of wanted) {
-					const label = labelElementFor(container, entry.name);
-					const target = label === null ? null : markerTargetFor(label);
+					const key = workspaceDotKey(entry);
+					if (key === undefined) { missed++; continue; }
+					// The browser's own row key first; the title walk-up is only for a build
+					// that stamps no Workspace keys (or an entry the snapshot could not name).
+					const keyedRow = workspaceRowElement(container, entry.id);
+					let target = keyedRow === null ? null : folderTargetFor(keyedRow);
+					if (target === null && keyedRow === null) {
+						const label = labelElementFor(container, entry.name);
+						target = label === null ? null : markerTargetFor(label);
+					}
 					if (target === null) { missed++; continue; }
 					const row = target.row;
-					if (existingMarker(row, WS_DOT_ATTR, entry.name) !== null) { placed++; continue; }
+					if (existingMarker(row, WS_DOT_ATTR, key) !== null) { placed++; continue; }
 					const icon = target.icon;
 					const rowRect = row.getBoundingClientRect();
 					const anchorRect = icon.getBoundingClientRect();
@@ -1338,9 +1633,9 @@ window.__ModuleLoader__.load({
 						row.style.position = "relative";
 					}
 					const dot = document.createElement("span");
-					dot.setAttribute(WS_DOT_ATTR, entry.name);
+					dot.setAttribute(WS_DOT_ATTR, key);
 					dot.setAttribute("aria-hidden", "true");
-					dot.title = entry.name + " · " + entry.count;
+					dot.title = (typeof entry.name === "string" && entry.name !== "" ? entry.name : key) + " · " + entry.count;
 					dot.style.cssText = "position:absolute;pointer-events:none;width:8px;height:8px;border-radius:50%;"
 						+ "background:#e5484d;box-shadow:0 0 0 1.5px var(--dsw-alias-bg-layer-1,#fff);"
 						+ "left:" + Math.round(anchorRect.right - rowRect.left - 4) + "px;"
@@ -1352,7 +1647,7 @@ window.__ModuleLoader__.load({
 				// Session rows: the marker rides inline right after the title, so it stays
 				// beside the name whatever the timestamp happens to say.
 				for (const entry of wantedRows) {
-					const target = sessionRowTarget(container, entry.id, entry.title);
+					const target = sessionRowTarget(container, entry.id, entry.title, legacyTitleMatch);
 					if (target === null) { missed++; continue; }
 					if (existingMarker(target.row, ROW_DOT_ATTR, entry.id) !== null) { placed++; continue; }
 					const dot = document.createElement("span");
@@ -1432,7 +1727,21 @@ 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.
+			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);
+			}, []);
+			const currentIds = currentSessionIds(list, { panelActive, visible, 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
@@ -1505,19 +1814,21 @@ window.__ModuleLoader__.load({
 				};
 			}, [staySignature, delayMs]);
 			React.useEffect(() => { emitRealBadge(count, items); }, [count, items]);
-			// The workspace rows are labelled with the workspace TITLE, which is not
-			// always the cwd basename, so map session → title from the official snapshot.
+			// 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
+			// the cwd basename, and not always equal to the stored title either).
 			React.useEffect(() => {
-				const titles = {};
+				const owners = {};
 				const list = workspaces !== null && typeof workspaces === "object" && Array.isArray(workspaces.items) ? workspaces.items : [];
 				for (const workspace of list) {
 					if (workspace === null || typeof workspace !== "object") continue;
+					if (!Array.isArray(workspace.sessionIds)) continue;
+					const id = typeof workspace.workspaceId === "string" ? workspace.workspaceId : "";
 					const title = typeof workspace.title === "string" ? workspace.title : "";
-					if (title === "" || !Array.isArray(workspace.sessionIds)) continue;
-					for (const id of workspace.sessionIds) titles[id] = title;
+					for (const sessionId of workspace.sessionIds) owners[sessionId] = { id, title };
 				}
 				emitSidebarMarks({
-					workspaces: dotsFromItems(items, titles),
+					workspaces: dotsFromItems(items, owners),
 					sessions: items.map((item) => ({ id: item.id, title: item.title }))
 				});
 			}, [items, workspaces]);
@@ -2355,6 +2666,10 @@ window.__ModuleLoader__.load({
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-icon-custom: dictionaries");
 			const t = ctx.locale.bind(NS);
 			const rpc = ctx.connection.rpc;
+			// The watermark's Host half rides the same connection as every other RPC.
+			// Setting it here (not at module scope) is what keeps the store usable in a
+			// test harness with no connection: pushes stay no-ops, the badge still works.
+			seenRpc = rpc;
 			// Pull the host state once, so the brand mark and the badge are correct
 			// before the settings section is ever opened. The unread rule rides its
 			// own endpoint: the icon RPCs keep their pre-badge response shape.
@@ -2366,8 +2681,16 @@ window.__ModuleLoader__.load({
 					if (resp === null || typeof resp !== "object" || resp.ok !== true) return;
 					// The rule response carries the Host's clock; it is what puts the seen
 					// watermark (and a legacy browser-domain store) into the Host's domain.
-					if (resp.value !== null && typeof resp.value === "object") noteHostClock(resp.value.hostNow);
+					// It also carries the Host's watermark table, which merges in here —
+					// then the first push sends the union back, which is both the migration
+					// (marks this browser made before 0.11.2) and the self-heal (a Host file
+					// that was lost or pruned gets this browser's copy back).
+					if (resp.value !== null && typeof resp.value === "object") {
+						noteHostClock(resp.value.hostNow);
+						if (adoptHostSeen(resp.value.seen)) saveSeenState();
+					}
 					emitUnreadConfig(resp.value);
+					scheduleHostSync();
 				})
 				.catch(() => {});
 			// Keep "the last moment this browser was here" fresh, so an ending that
@@ -2390,18 +2713,33 @@ window.__ModuleLoader__.load({
 			// Re-sample the Host↔browser clock offset after a sleep/resume, which is the
 			// one moment the two can drift apart mid-page. Throttled: it is one small
 			// RPC per visible-again, and never on beforeunload (nothing would come back).
+			// The same response carries the Host's watermark, so this is also how a
+			// SECOND device learns that something was read elsewhere — a page that is
+			// simply left open converges within a minute without a reload. Coming back
+			// into view is also the natural moment to retry a failed push.
 			ctx.effect(() => {
 				let sampledAt = 0;
 				const sample = () => {
 					if (document.visibilityState === "hidden") return;
+					scheduleHostSync();
 					if (Date.now() - sampledAt < 60000) return;
 					sampledAt = Date.now();
 					rpc.call("/api", "iconCustom/getUnreadRule", { args: {} })
-						.then((resp) => { if (resp && resp.ok === true && resp.value !== null && typeof resp.value === "object") noteHostClock(resp.value.hostNow); })
+						.then((resp) => {
+							if (resp === null || typeof resp !== "object" || resp.ok !== true) return;
+							const value = resp.value !== null && typeof resp.value === "object" ? resp.value : null;
+							if (value === null) return;
+							noteHostClock(value.hostNow);
+							if (adoptHostSeen(value.seen)) { saveSeenState(); emitUnreadPoke(); }
+						})
 						.catch(() => {});
 				};
 				window.addEventListener("visibilitychange", sample);
-				return () => window.removeEventListener("visibilitychange", sample);
+				const interval = window.setInterval(sample, 60000);
+				return () => {
+					window.removeEventListener("visibilitychange", sample);
+					window.clearInterval(interval);
+				};
 			}, "dsh-icon-custom: host clock sample");
 			// Brand-mark seat: replaces only the whale mark (verified: a
 			// third-party registration wins over the official occupant and the

package/lib/index.js

@@ -29,12 +29,16 @@ import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import {
 	LAST_TURN_END_KEY,
+	UNREAD_SEEN_VERSION,
 	applyLastTurnEnd,
 	initLastTurnEnd,
 	lastTurnEndStateSchema,
 	lastTurnEndView,
 	lastTurnEndViewSchema,
-	normalizeUnreadConfig
+	mergeSeen,
+	normalizeSeen,
+	normalizeUnreadConfig,
+	pruneSeen
 } from './unread.js'
 
 const MAX_BYTES = 10 * 1024 * 1024 // 10 MB
@@ -330,6 +334,10 @@ export class FaviconCustomService extends TypertRemoteService {
 		this.libraryDir = join(this.storageDir, 'library')
 		this.indexPath = join(this.storageDir, 'library.json')
 		this.unreadPath = join(this.storageDir, 'unread.json')
+		// The "I have looked at this session" watermark. Host-owned on purpose: it
+		// survives a cleared browser profile and means the same thing on every
+		// device, while each browser keeps its own copy as cache + offline queue.
+		this.seenPath = join(this.storageDir, 'unread-seen.json')
 		// { activeId, icons: { [id]: { id, mime, ext, name, size, savedAt, rev, pwa, logo } } }
 		this.library = { activeId: null, icons: {} }
 		// The active icon's loaded state: { rev, mime, ext, name, size, savedAt, pwa, logo, bytes } | null
@@ -338,10 +346,13 @@ export class FaviconCustomService extends TypertRemoteService {
 		// Kept in its own file so a settings change can never corrupt the icon
 		// library index.
 		this.unread = normalizeUnreadConfig(null)
+		// Host-side watermark: { [sessionId]: endAt } — see lib/unread.js.
+		this.seen = {}
 		// Platform PWA manifest (raw + parsed), read once at startup.
 		this.baseManifest = loadBaseManifest()
 		this._load()
 		this._loadUnread()
+		this._loadUnreadSeen()
 		// "How did this session's last turn end" as an official session
 		// projection. Optional registration on purpose: this plugin is a display
 		// plugin first, so a deployment without the projection service loses the
@@ -439,6 +450,30 @@ export class FaviconCustomService extends TypertRemoteService {
 		return writeFile(this.unreadPath, JSON.stringify(this.unread, null, 2))
 	}
 
+	/**
+	 * Load the host-side watermark.
+	 *
+	 * A missing file, an unknown `version` (a future format), or a corrupt document
+	 * all open as an EMPTY table — never as a guess. An empty table cannot light
+	 * anything up: the client re-baselines a session it has no mark for at "the last
+	 * time this browser was here", so old endings stay read.
+	 */
+	_loadUnreadSeen() {
+		try {
+			const raw = JSON.parse(readFileSync(this.seenPath).toString('utf8'))
+			if (raw === null || typeof raw !== 'object' || raw.version !== UNREAD_SEEN_VERSION) return
+			this.seen = pruneSeen(normalizeSeen(raw.seen))
+		} catch { /* no watermark yet */ }
+	}
+
+	/** Persist the watermark (best effort, advisory file). Temp then rename, so a crash never truncates it. */
+	async _saveUnreadSeen() {
+		await mkdir(this.storageDir, { recursive: true })
+		const tmp = `${this.seenPath}.tmp`
+		await writeFile(tmp, JSON.stringify({ version: UNREAD_SEEN_VERSION, seen: this.seen }, null, 2))
+		await rename(tmp, this.seenPath)
+	}
+
 	/** Currently active icon as a JSON-safe status object (no raw bytes). */
 	status() {
 		const c = this.current
@@ -482,14 +517,42 @@ export class FaviconCustomService extends TypertRemoteService {
 	}
 
 	/**
-	 * The rule as the client reads it, plus the Host's clock.
+	 * typert endpoint: merge this browser's "seen" watermarks into the Host's copy.
+	 *
+	 * The watermark lives here so that "I have looked at this session" survives a
+	 * cleared browser profile and holds across devices; each browser keeps its own
+	 * copy as a cache and offline queue. Merging is max-per-session and therefore
+	 * idempotent: re-sending the whole table is harmless (that is also how a fresh
+	 * browser migrates its localStorage marks up), and a stale client can never move
+	 * a mark backwards.
+	 * @param request - `{ marks: { [sessionId]: endAt } }`; dirty keys/values are dropped.
+	 * @returns `{ seen }` — the merged table, authoritative for the caller.
+	 */
+	async setUnreadSeen(request) {
+		if (request === null || typeof request !== 'object') {
+			throw new Error('缺少 marks 参数')
+		}
+		const merged = mergeSeen(this.seen, request.marks)
+		this.seen = pruneSeen(merged.seen)
+		// The write is part of the contract, NOT swallowed: this feature's whole value is
+		// that the watermark survives, so answering "ok" while nothing reached the disk
+		// is the one failure nobody can see (the client would stop retrying and another
+		// device would keep its old answer forever). Throwing lets the client warn once
+		// and retry with backoff.
+		await this._saveUnreadSeen()
+		return { seen: { ...this.seen } }
+	}
+
+	/**
+	 * The rule as the client reads it, plus the Host's clock and watermark.
 	 *
 	 * `hostNow` is here because the badge compares the Host's `turn/end.time`
-	 * against a watermark this browser keeps: without a Host time sample the
-	 * browser has to guess that domain from its own clock, and a browser a few
-	 * seconds behind the Host then clears nothing. It rides this existing
-	 * response instead of a new endpoint, so an older client simply ignores it.
-	 * @returns the stored rule with `hostNow`.
+	 * against a watermark: without a Host time sample the browser has to guess that
+	 * domain from its own clock, and a browser a few seconds behind the Host then
+	 * clears nothing. `seen` is the watermark itself — the authority the client
+	 * merges into its local cache. Both ride this existing response instead of a new
+	 * read endpoint, so an older client simply ignores the field it does not know.
+	 * @returns the stored rule with `hostNow` and `seen`.
 	 */
 	_unreadRuleView() {
 		return {
@@ -498,7 +561,8 @@ export class FaviconCustomService extends TypertRemoteService {
 			workspaceDot: this.unread.workspaceDot,
 			appBadge: this.unread.appBadge,
 			clearDelaySec: this.unread.clearDelaySec,
-			hostNow: Date.now()
+			hostNow: Date.now(),
+			seen: { ...this.seen }
 		}
 	}
 

package/lib/typert.host.js

@@ -62,7 +62,14 @@ const unreadRuleSchema = z.object({
 	 * 客户端用它把"看过"水位换算进宿主时钟域(`turn/end.time` 也是宿主时钟):
 	 * 浏览器与宿主差几秒,红点就会永远清不掉。
 	 */
-	hostNow: z.number()
+	hostNow: z.number(),
+	/**
+	 * 宿主持有的"已读"水位线:会话 id → 已确认的最后一次 `turn/end`(宿主时钟域)。
+	 *
+	 * 它是真相,浏览器那份是缓存 + 离线队列;随本响应一起下发是为了不新增读端点
+	 * (老客户端忽略这个字段即可)。客户端拿它按会话取 max 合并。
+	 */
+	seen: z.record(z.string(), z.number())
 })
 
 const setUnreadRuleRequestSchema = z.object({
@@ -73,6 +80,15 @@ const setUnreadRuleRequestSchema = z.object({
 	clearDelaySec: z.number().int().nonnegative().max(600).optional()
 })
 
+/** 一次水位线同步:浏览器把自己那份交上来,宿主逐会话取 max 后回权威表。 */
+const setUnreadSeenRequestSchema = z.object({
+	marks: z.record(z.string(), z.number())
+})
+
+const unreadSeenSchema = z.object({
+	seen: z.record(z.string(), z.number())
+})
+
 const setIconResultSchema = statusSchema
 
 export const TYPERT = {
@@ -221,6 +237,31 @@ export const TYPERT = {
 				create: () => unreadRuleSchema
 			},
 			sourceLocation: { file: 'lib/index.js', line: 1, column: 1 }
+		},
+		{
+			id: 'dsh-icon-custom#iconCustom/setUnreadSeen',
+			service: 'iconCustom',
+			namespace: 'iconCustom',
+			method: 'setUnreadSeen',
+			invocation: { kind: 'direct' },
+			parameters: [
+				{
+					name: 'request',
+					wire: 'request',
+					source: 'json',
+					codec: {
+						mode: 'strict',
+						typeSymbol: 'dsh-icon-custom#iconCustom/setUnreadSeen:request',
+						create: () => setUnreadSeenRequestSchema
+					}
+				}
+			],
+			result: {
+				mode: 'strict',
+				typeSymbol: 'dsh-icon-custom#iconCustom/setUnreadSeen:result',
+				create: () => unreadSeenSchema
+			},
+			sourceLocation: { file: 'lib/index.js', line: 1, column: 1 }
 		}
 	],
 	model: {
@@ -281,8 +322,8 @@ export const TYPERT = {
 					{
 						kind: 'method',
 						name: 'getUnreadRule',
-						signature: 'async getUnreadRule(): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; appBadge: boolean; clearDelaySec: number; hostNow: number }>',
-						description: "Read the unread-badge rule.",
+						signature: 'async getUnreadRule(): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: boolean; appBadge: boolean; clearDelaySec: number; hostNow: number; seen: Record<string, number> }>',
+						description: "Read the unread-badge rule, the Host clock and the seen watermark.",
 						summary: "Read the unread-badge rule.",
 						jsDoc: "/** Read the unread-badge rule. */",
 						tags: []
@@ -290,11 +331,20 @@ export const TYPERT = {
 					{
 						kind: 'method',
 						name: 'setUnreadRule',
-						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 }>',
+						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; seen: Record<string, 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. */",
 						tags: []
+					},
+					{
+						kind: 'method',
+						name: 'setUnreadSeen',
+						signature: 'async setUnreadSeen(request: { marks: Record<string, number> }): Promise<{ seen: Record<string, number> }>',
+						description: "Merge this browser's seen watermarks into the Host's copy (max per session).",
+						summary: "Merge the seen watermark.",
+						jsDoc: "/** Merge the seen watermark. */",
+						tags: []
 					}
 				],
 				types: []

package/lib/unread.js

@@ -164,3 +164,82 @@ export const lastTurnEndViewSchema = z.object({
 	endAt: z.number(),
 	reason: z.string().nullable()
 })
+
+// ---------------------------------------------------------------------------
+// 水位线(宿主持有的"已读"标记)
+//
+// 这是这套东西唯一的真相:浏览器那份降级为缓存兼离线队列。放宿主有两个理由——
+// 清掉浏览器数据不再等于"全部未读",以及"我看过了"跨设备一致。
+// 判定精度不变:仍是"进入会话并连续待够 N 秒"才算看过,规则在 client/client.js。
+// ---------------------------------------------------------------------------
+
+/** 水位线文件的版本;不认识的版本当空库(猜错会把红点全点亮)。 */
+export const UNREAD_SEEN_VERSION = 1
+
+/** 一个库最多留多少条水位线(client/client.js 的 SEEN_MAX 是它的镜像)。 */
+export const UNREAD_SEEN_MAX = 400
+
+/** 单个会话 id 的长度上限:挡脏输入,不是安全边界。 */
+const SESSION_ID_MAX = 128
+
+/** 水位线文件:`{ version, seen }`;`seen` 是 会话 id → 已确认的最后一次 `turn/end`(宿主时钟域)。 */
+export const unreadSeenFileSchema = z.object({
+	version: z.number(),
+	seen: z.record(z.string(), z.number())
+})
+
+/**
+ * 把任意输入夹成一张干净的水位线表。
+ * 脏 key(空、超长、非字符串)与脏值(非有限数、≤0)直接丢掉,绝不写回文件。
+ * @param input - 文件内容、RPC 载荷,或任何东西
+ * @returns 只含合法条目的新对象
+ */
+export function normalizeSeen(input) {
+	const out = {}
+	if (input === null || typeof input !== 'object') return out
+	for (const [id, at] of Object.entries(input)) {
+		if (typeof id !== 'string' || id === '' || id.length > SESSION_ID_MAX) continue
+		if (typeof at !== 'number' || !Number.isFinite(at) || at <= 0) continue
+		out[id] = at
+	}
+	return out
+}
+
+/**
+ * 合并一批水位线:逐会话取 max。
+ *
+ * "标记永不倒退"是这套东西唯一的并发保护:两个浏览器(或两个 dsh 进程)同时写,
+ * 后写者也不会把别人更新的标记盖回旧的——那会让已清掉的红点"诈尸"。
+ * @param seen - 现有水位线表
+ * @param marks - 要并入的标记
+ * @returns `{ seen, changed }`,`changed` 表示是否有条目前进
+ */
+export function mergeSeen(seen, marks) {
+	const base = normalizeSeen(seen)
+	const incoming = normalizeSeen(marks)
+	let changed = false
+	for (const [id, at] of Object.entries(incoming)) {
+		const previous = base[id]
+		if (typeof previous === 'number' && previous >= at) continue
+		base[id] = at
+		changed = true
+	}
+	return { seen: base, changed }
+}
+
+/**
+ * 只留最新的 N 条水位线。
+ *
+ * 丢掉的都是"很久以前就看过"的记录,不会把红点变回来:客户端对没有标记的会话
+ * 按"这台浏览器上次在线"重新起基线,老结束仍算已读(见 client/client.js 的
+ * `ensureSeenBaseline`)。所以按时间保留最新即可。
+ * @param seen - 水位线表
+ * @param max - 上限
+ * @returns 新对象
+ */
+export function pruneSeen(seen, max = UNREAD_SEEN_MAX) {
+	const entries = Object.entries(normalizeSeen(seen))
+	if (entries.length <= max) return Object.fromEntries(entries)
+	entries.sort((a, b) => b[1] - a[1])
+	return Object.fromEntries(entries.slice(0, max))
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@cowwo/dsh-icon-custom",
-  "version": "0.11.1",
+  "version": "0.15.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",
   "license": "MIT",
   "scripts": {
-    "test": "node test/app-badge.mjs && node test/unread-panel.mjs && node test/unread-clear.mjs"
+    "test": "node test/app-badge.mjs && node test/unread-panel.mjs && node test/unread-clear.mjs && node test/unread-rows.mjs && node test/unread-seen.mjs && node test/unread-host-sync.mjs"
   },
   "dependencies": {
     "jimp": "^1.6.1",