@cowwo/dsh-icon-custom 0.10.2 → 0.12.0

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
@@ -459,7 +494,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 +504,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) {
@@ -482,22 +517,52 @@ 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 {
 			reasons: this.unread.reasons,
 			pending: this.unread.pending,
 			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

@@ -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),
 	/**
@@ -60,16 +62,33 @@ 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({
 	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()
 })
 
+/** 一次水位线同步:浏览器把自己那份交上来,宿主逐会话取 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 = {
@@ -218,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: {
@@ -278,8 +322,8 @@ export const TYPERT = {
 					{
 						kind: 'method',
 						name: 'getUnreadRule',
-						signature: 'async getUnreadRule(): Promise<{ reasons: Record<string, boolean>; pending: boolean; workspaceDot: 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: []
@@ -287,11 +331,20 @@ 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; 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

@@ -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)
 	}
 }
@@ -153,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,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.12.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 && node test/unread-rows.mjs && node test/unread-seen.mjs && node test/unread-host-sync.mjs"
+  },
   "dependencies": {
     "jimp": "^1.6.1",
     "zod": "^4.4.3"