@cowwo/dsh-icon-custom 0.10.2 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +34 -0
  2. package/README.zh.md +39 -4
  3. package/client/client.js +582 -84
  4. package/lib/index.js +75 -10
  5. package/lib/typert.host.js +57 -4
  6. package/lib/unread.js +92 -2
  7. package/package.json +5 -2
package/README.md CHANGED
@@ -43,6 +43,38 @@ Notes:
43
43
  - It can be toggled at any time after upload — no re-upload needed.
44
44
  - This only affects the sidebar brand mark (the one next to `deepseek HARNESS`); PWA/installed-app icons are a separate option above.
45
45
 
46
+ ## App icon badge (the red dot on the system icon)
47
+
48
+ 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.
49
+
50
+ > ⚠️ **What it looks like on Windows depends on which browser installed the app**:
51
+ > - **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+`.
52
+ > - **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.
53
+ >
54
+ > 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).
55
+
56
+ Platform support as of 0.11.1:
57
+
58
+ | Platform | Badge | Status |
59
+ |---|---|---|
60
+ | 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** |
61
+ | 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) |
62
+ | macOS Chrome / Edge 81+ | Dock badge | Unverified (the code is ready; same single call) |
63
+ | macOS Safari 17+ ("Add to Dock") | Dock badge | Unverified |
64
+ | 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 |
65
+ | 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) |
66
+ | HarmonyOS | — | No public evidence of any implementation; **expected unsupported** (native badges there are ArkTS-only) |
67
+ | Firefox / Linux Chromium | — | No API / no OS API — calls resolve and do nothing |
68
+
69
+ 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.
70
+
71
+ Two behaviours that look like bugs but are not:
72
+
73
+ - **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.
74
+ - **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.
75
+
76
+ 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).
77
+
46
78
  ## Format support
47
79
 
48
80
  - **SVG** — recognized by content (`<svg`), validated against script / event‑handler / `javascript:` injection. Rasterized to PNG in the browser before upload.
@@ -56,6 +88,8 @@ The uploaded file is stored verbatim (never re‑encoded) so the favicon keeps i
56
88
 
57
89
  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.
58
90
 
91
+ 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.
92
+
59
93
  ## License
60
94
 
61
95
  MIT
package/README.zh.md CHANGED
@@ -58,14 +58,47 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
58
58
  规则:
59
59
 
60
60
  - 数字 = **几个会话**在等你(不是几件事);同一个会话只占一格。
61
- - 只有子代理会话不计。**你正开着的那个会话也算**——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分;要清掉它,切走再切回来即可。
62
- - **已读记在每个浏览器自己身上**(localStorage):进过 = 处理过,刷新/重启不会"复活";装插件之前的历史结束也不算。
63
- - **可以要求"待够才算已读"**:设置页填一个秒数(默认 0)。填 0 = 进去就算已读(红点立即消失);填 N = 你要在那个会话里**连续待满 N 秒**它才算看过——中途切走、或它又跑完一轮,都清零重数,刷新页面也重新数。上限 600 秒。
61
+ - 只有子代理会话不计。**你正开着的那个会话也算**——窗口可能被最小化、页面可能切到后台,这里无从判断你在不在看,所以不做这个区分;**要清掉它,切走再切回来即可**(你人已经在里面时又结束的那一轮不会自动消,见下一条)。
62
+ - **已读记在宿主**(`$DSH_HOME/custom-favicon/unread-seen.json`):进过 = 处理过,刷新/重启不会"复活",**任何一台设备上看过,所有设备都不再提醒**(开着的页面最多约一分钟收敛,刷新则立刻)。浏览器自己也留一份,但只当缓存兼离线队列——所以清站点数据、换浏览器、无痕窗口都不会把"已读"丢回去。装插件之前的历史结束也不算。
63
+ - **可以要求"待够才算已读"**:设置页填一个秒数(默认 0)。填 0 = 进去就算已读(红点立即消失);填 N = 你要在那个会话里**连续待满 N 秒**它才算看过,中途切走就清零重数,刷新页面也重新数。上限 600 秒。
64
+ **计时只认"你进入会话时已经存在的那次结束"**:你人已经在会话里的时候它又跑完一轮,那一轮**不算数**——红点会一直亮着,等你**切走再进来**才消。这样"我正看着的会话跑完了"这件事不会被几秒钟后自动抹掉(0.11.1 起;此前是"停留满 N 秒就把最新那次结束也标成已读",红点只闪一下)。
64
65
  - 数据全部来自官方:`turn/end` 事件经官方 session projection 折叠,加上官方的"等待交互"注册表——**不依赖任何其他插件**。
65
66
  - 设置页的**数据来源**可以切到"手动测试",手填数字试看效果。
66
- - **工作区和会话行上的红点(实验)**:侧栏每个**工作区**那一行的文件夹图标右上角一个小红点,每个**有未读的会话**在标题右边跟一个小红点——一眼看出"事情在哪个工作区的哪个会话"。这一项是**贴着页面结构**做的——DSH 大版本升级后**可能失效**,失效时只会变成"不显示",**不影响**红点数字、清单和跳转;设置页里有一个开关可以随时关掉它。
67
+ - **工作区和会话行上的红点(实验)**:侧栏每个**工作区**那一行的文件夹图标右上角一个小红点(收起的工作区里有多少未读,就看它),每个**有未读的会话**在标题右边跟一个小红点——一眼看出"事情在哪个工作区的哪个会话"。定位走 DSH 自己的 `data-row-key`(工作区、会话都按 **id**,不靠标题文字):标题重复不会串行,**折叠起来的会话不单独画点**——它的行没有渲染,由工作区那一行的点和「待处理」清单代表它。这一项是**贴着页面结构**做的——DSH 大版本升级后**可能失效**,失效时只会变成"不显示",**不影响**红点数字、清单和跳转;设置页里有一个开关可以随时关掉它。
67
68
  - **想知道具体是哪个会话?** 侧栏「工作区」标题的**右上角**有一个**红底数字**(没有待处理时是灰色 0,位置不变);点开是待处理会话清单,**按工作区分组**(工作区名 · 会话名 · 在等你/刚结束),点其中一条**直接跳到那个会话**。
68
69
 
70
+ ## 应用图标角标(系统图标上的红点)
71
+
72
+ 把网页**安装为应用**后,同一个未读数字也会显示在**系统图标**上。设置在**设置 → icon管理 → 未读红点**里的「在系统应用图标上显示红点」,**默认打开**;数字与页内红点**严格同值**(同一份计算,不额外截断),所以两个地方永远一致。
73
+
74
+ > ⚠️ **Windows 上它长什么样——取决于你用什么浏览器装**:
75
+ > - **Chrome 装的**:Chrome **自己画**一张覆盖图标贴在任务栏按钮上——**深灰圆 + 白色数字**,位置在图标右下角。**不是红色圆点,也不是我们图标的一部分**。数字超过 99 显示 `99+`。
76
+ > - **Edge 装的**:Edge 走 **Windows 系统徽章通道**,外观是系统样式。官方文档说支持数字和空角标,但本机在 Windows 11 上实测(2026-10-01)控制台直接 `navigator.setAppBadge(7)` 也只出现一个系统蓝点。插件已加 **5 秒低频看门狗**,会持续重设正向数字,但最终画成数字还是点由 Edge/Windows 决定;想要稳定数字,可用 Chrome 安装。
77
+ >
78
+ > 两种情况下都:**只在应用窗口开着的时候存在**——关掉窗口角标就消失(这不是插件坏了),窗口全关之后也不会再更新数字(没有推送服务,页面不在就没有代码在跑)。
79
+
80
+ 平台支持情况(截至 0.11.1):
81
+
82
+ | 平台 | 角标 | 状态 |
83
+ |---|---|---|
84
+ | Windows **Chrome** 81+ | 深灰圆 + **白色数字**(Chrome 自己画的覆盖图标,右下角) | 官方文档示例图 + 源码印证;**本机待实测** |
85
+ | Windows **Edge** 81+ | 走 Windows 系统徽章通道;官方文档支持数字,但本机实测数字被画成点(待 Edge/Windows 侧修复) | **本机实测异常**(2026-10-01) |
86
+ | macOS Chrome / Edge 81+ | Dock 角标 | 未验证(代码已就绪,同一行不会额外做事) |
87
+ | macOS Safari 17+(「添加到程序坞」) | Dock 角标 | 未验证 |
88
+ | iOS / iPadOS Safari 16.4+(加到主屏) | 主屏图标上的数字 | 未验证;且**必须先授予通知权限**才会显示——本插件目前不申请通知权限,所以 iOS 上暂时不会出现 |
89
+ | Android Chrome / Edge | —— | **系统不支持**:Chromium 在安卓上把角标实现编译掉了;启动器上的圆点只能由**通知**产生(本插件不发通知) |
90
+ | 鸿蒙 | —— | 无任何公开实现证据,**预计不支持**(鸿蒙的原生角标只能用 ArkTS 设) |
91
+ | Firefox / Linux Chromium | —— | 不支持 / 没有系统 API,调用静默无效 |
92
+
93
+ 设置页里那行「当前环境」只报**本机此刻的事实**(是不是安全上下文、有没有这个 API、是不是已安装的应用),它**不**承诺角标一定会出现——因为**探测到 API ≠ 会显示**(安卓、Linux 上就是如此;iOS 还多一道通知权限)。是否真正显示由系统决定。
94
+
95
+ 顺便说明两个容易被当成 bug 的现象:
96
+
97
+ - **在浏览器标签页里填「手动测试」数字,任务栏没有角标** —— 这是对的:角标只属于**安装后的应用窗口**,普通标签页调用是静默无操作。
98
+ - **局域网 `http://192.168.x.x` 访问时没有角标** —— Badging API 要求安全上下文,这时设置页会提示"请用 localhost 或 https 访问"。
99
+
100
+ 设计取舍(为什么不做通知、不做 service worker、为什么不按平台门禁)记在 [`docs/adr/0005-app-icon-badge.md`](./docs/adr/0005-app-icon-badge.md)。
101
+
69
102
  ## 支持的格式
70
103
 
71
104
  - **SVG** — 按内容(`<svg`)识别,并拦截 `<script>` / 事件属性 / `javascript:` 注入。上传前会在浏览器里栅格化成 PNG。
@@ -79,6 +112,8 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
79
112
 
80
113
  图标按用户保存在 `$DSH_HOME/custom-favicon/`。**恢复默认**只清除当前生效标记,已保存的文件会保留,为将来的图标库 UI 做准备。
81
114
 
115
+ 同一个目录里还有两份 JSON:`unread.json`(哪些结束原因算未读)与 `unread-seen.json`(已读水位线,`{ version, seen: { 会话id → endAt } }`,上限 400 条、写入是 temp+rename)。两份都是**可丢的**:删掉 `unread.json` 回到默认规则,删掉 `unread-seen.json` 则每台浏览器按"上次在线时间"重新起基线(不会把历史红点全部点亮)。
116
+
82
117
  ## 许可证
83
118
 
84
119
  MIT