@cowwo/dsh-icon-custom 0.16.0 → 0.18.0

package/README.md

@@ -43,6 +43,19 @@ 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.
 
+## Running marks (yellow)
+
+While a session is **running**, a yellow mark appears in four places: after the sidebar's **"工作区" label** a yellow number (how many sessions are running right now), a yellow dot on each **workspace folder icon**, a yellow dot on each **session row**, and the same number on the **top-left logo** and in the **bottom-right corner of the tab icon**. Live, no reload needed.
+
+- **How it sits next to the unread red dot**: numbers stack — red top-right, yellow bottom-right (after the label, on the top-left logo, and on the tab icon alike); dots sit side by side — **red on the left, yellow on the right** (on the workspace folder icon and on the session row alike). On the folder icon the red dot steps one dot to the left while the yellow is there, and steps back the moment it is gone. Each feature has its own switch — turning the yellow off leaves every red dot in place.
+- **The yellow mark IS the official "running"**: the session has a turn in flight and is not parked waiting for you — while it waits, the official row shows the amber "waiting for approval / waiting for answer / plan review" and the yellow goes dark. It tracks the official row's **grey spinner** exactly; the only difference is colour — the official one is deliberately quiet, this one is meant to be seen.
+- **Every fact is official**: each session's `running` from the session list (computed by the host, pushed live). The plugin stores nothing and infers nothing, so a reload is immediately right and a **process restart never leaves a yellow mark stuck on**.
+- **Sub-agents never count**: sub-agent sessions are not rendered in the sidebar at all (the same rule the red dot and the official row follow).
+- Above 99 it shows `99+`, the same rule as the red count; **the two numbers are always the same size** — when both appear they shrink together to the largest pair that fits, stacked and never overlapping (at a 16px tab icon or a 24px logo two digits are already tight: a big one beside a small one, or two overlapping, would make both unreadable), and a number shown alone keeps the normal size (so the small/medium/large setting applies only while a number is on its own — with both shown, all three sizes draw the same).
+- The switch is in **Settings → icon管理 → Running marks** and is **on by default**.
+
+> Why is the red count top-right and the yellow dot bottom-right instead of simply recolouring the official grey spinner? See [`docs/adr/0010-running-mark-is-a-second-projection.md`](./docs/adr/0010-running-mark-is-a-second-projection.md).
+
 ## 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.
@@ -53,27 +66,29 @@ Once the page is **installed as an app**, the same unread number is also shown o
 >
 > 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 support as of 0.18.0 (every row has a source; see ADR 0005 / 0009):
 
 | 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 |
+| macOS **Chrome / Edge** 81+ | Dock badge (red, numeric) | Confirmed in source (MDN: Chrome supports Windows and macOS since 81; `badge_manager_delegate_mac.cc` → app shim → `NSApp.dockTile.badgeLabel`); **not measured on a Mac here**. Needs **no** notification permission, but only works for the **running installed app** |
+| macOS **Safari 17+** ("Add to Dock", macOS Sonoma 14+) | Dock badge (red, numeric) | Supported per Apple's own documentation; it **only appears after notifications are granted** — that is what the permission row in settings is for |
+| iOS / iPadOS Safari 16.4+ (Add to Home Screen) | Number on the home-screen icon | Supported; also **requires notifications to be granted first** (the "Allow notifications" button does that) |
 | 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.
+**About the "notifications permission" row (since 0.17.0)**: below the badge switch the settings page now shows one local reading (**granted / not granted / denied / no Notification API in this browser**) plus an "Allow notifications" button that appears only while the permission is still undecided (nothing left to ask once granted; once denied the browser refuses to prompt again, so the row says where to change it instead). It is **not a plugin switch** — it is Apple's rule: Safari ties the badge permission to the notifications permission, and a Dock or home-screen web app that has not been allowed to notify simply has its `setAppBadge()` calls dropped. **Chrome / Edge need none of this**, and the permission is only ever used to draw the badge — the plugin sends no notifications. If the permission moves outside the page (changed in System Settings, or prompted by another tab) the row follows; the moment it becomes *granted* the current number is re-asserted at once, because every earlier call was dropped while there was no permission.
+
+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 WebKit 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).
+The reasoning (why no notifications are sent, 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); the notifications-permission row (why it is probed separately, why it never gates the badge call) is in [`docs/adr/0009-notification-permission.md`](./docs/adr/0009-notification-permission.md).
 
 ## Format support
 
@@ -88,7 +103,7 @@ 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.
+That directory also holds three JSON files: `unread.json` (which turn-end reasons count as unread), `unread-seen.json` (the seen watermark, `{ version, seen: { sessionId → endAt } }`, capped at 400 entries and written temp-then-rename) and `running.json` (the running-mark switch — one boolean). All three are **disposable**: deleting the first restores the default rule, the second makes each browser re-baseline at "the last time it was open" (which does not resurrect old dots), and the third restores "show the yellow marks". **None of them stores what is running** — that is always the official host's live fact. 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
 

package/README.zh.md

@@ -67,6 +67,19 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
 - **工作区和会话行上的红点(实验)**:侧栏每个**工作区**那一行的文件夹图标右上角一个小红点(收起的工作区里有多少未读,就看它),每个**有未读的会话**在标题右边跟一个小红点——一眼看出"事情在哪个工作区的哪个会话"。定位走 DSH 自己的 `data-row-key`(工作区、会话都按 **id**,不靠标题文字):标题重复不会串行,**折叠起来的会话不单独画点**——它的行没有渲染,由工作区那一行的点和「待处理」清单代表它。这一项是**贴着页面结构**做的——DSH 大版本升级后**可能失效**,失效时只会变成"不显示",**不影响**红点数字、清单和跳转;设置页里有一个开关可以随时关掉它。
 - **想知道具体是哪个会话?** 侧栏「工作区」标题的**右上角**有一个**红底数字**(没有待处理时是灰色 0,位置不变);点开是待处理会话清单,**按工作区分组**(工作区名 · 会话名 · 在等你/刚结束),点其中一条**直接跳到那个会话**。
 
+## 进行中黄点
+
+有会话**正在跑**时会四处出现黄色标记:**侧栏「工作区」标题后面**是黄色数字(此刻有几个在跑),**工作区文件夹图标上**是黄点,**会话行**上也是黄点,**左上角 Logo** 和**标签页图标的右下角**是同一个数字。实时推送,不需要刷新。
+
+- **和未读红点怎么排**:数字是上下排——红数字在右上、黄数字在右下(标题后面、左上角、标签页三处都一样);点是左右排——**红点在左、黄点在右**(工作区文件夹图标与会话行都一样)。文件夹上的红点在黄点出现时会向左让出一个点的宽度,黄点消失后退回原处。两个功能各有各的开关——关掉黄点,红点一个都不少。
+- **黄点就是官方的「进行中」**:会话有回合正在跑、而且没有停下来等你——你停下等审批 / 回答 / 计划待审的时候,官方那一行显示的是琥珀色标记,黄点也就不亮。它和官方行首那颗**灰色转圈**同进同出,差别只是颜色:官方做得安静,这里做得看得见。
+- **事实全部来自官方**:会话列表里每个会话的 `running`(宿主算好、实时推给浏览器),插件不落盘、不推断。所以刷新页面立刻就是对的,**进程重启也不会留下一个永远亮着的黄点**。
+- **子代理不算**:子代理会话根本不在侧栏里显示,它的运行不会让黄点亮起来(与红点同一条规矩,也和官方那一行一致)。
+- 数字超过 99 显示 `99+`,和红点角标同一条规矩;**两颗数字徽标一样大**:同时出现时它们一起缩到能容下的尺寸、上下排开不重叠(16px 标签页与 24px logo 上两个数字本来就挤,画成一大一小或叠在一起都会读不出来),只有一颗时保持原来的大小(也就是说"红点大小"那三档只在单独出现时生效,两颗同框时三档一样)。
+- 开关在**设置 → icon管理 → 进行中黄点**,**默认打开**。
+
+> 为什么红在上、黄在下,而不是干脆把官方那颗灰转圈染黄?见 [`docs/adr/0010-running-mark-is-a-second-projection.md`](./docs/adr/0010-running-mark-is-a-second-projection.md)。
+
 ## 应用图标角标(系统图标上的红点)
 
 把网页**安装为应用**后,同一个未读数字也会显示在**系统图标**上。设置在**设置 → icon管理 → 未读红点**里的「在系统应用图标上显示红点」,**默认打开**;数字与页内红点**严格同值**(同一份计算,不额外截断),所以两个地方永远一致。
@@ -77,27 +90,29 @@ SVG 会在浏览器里先栅格化成 512×512 PNG 再上传,ICO 则由后端提
 >
 > 两种情况下都:**只在应用窗口开着的时候存在**——关掉窗口角标就消失(这不是插件坏了),窗口全关之后也不会再更新数字(没有推送服务,页面不在就没有代码在跑)。
 
-平台支持情况(截至 0.11.1):
+平台支持情况(截至 0.18.0;每条都有出处,见 ADR 0005 / 0009):
 
 | 平台 | 角标 | 状态 |
 |---|---|---|
 | 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 上暂时不会出现 |
+| macOS **Chrome / Edge** 81+ | Dock 角标(红底数字) | 源码印证(MDN:Chrome 自 81 起支持 Windows 与 macOS;`badge_manager_delegate_mac.cc` → app shim → `NSApp.dockTile.badgeLabel`);**未在真机实测**。**不需要通知权限**,但只对**正在运行的已安装应用**有效 |
+| macOS **Safari 17+**(「添加到程序坞」,需 macOS Sonoma 14+) | Dock 角标(红底数字) | Apple 官方文档支持;**必须先授予通知权限**才会画——设置页那一行「通知权限」就是为它准备的 |
+| iOS / iPadOS Safari 16.4+(加到主屏) | 主屏图标上的数字 | 官方支持;同样**必须先授予通知权限**(可以用设置页的「允许通知」按钮申请) |
 | Android Chrome / Edge | —— | **系统不支持**:Chromium 在安卓上把角标实现编译掉了;启动器上的圆点只能由**通知**产生(本插件不发通知) |
 | 鸿蒙 | —— | 无任何公开实现证据,**预计不支持**(鸿蒙的原生角标只能用 ArkTS 设) |
 | Firefox / Linux Chromium | —— | 不支持 / 没有系统 API,调用静默无效 |
 
-设置页里那行「当前环境」只报**本机此刻的事实**(是不是安全上下文、有没有这个 API、是不是已安装的应用),它**不**承诺角标一定会出现——因为**探测到 API ≠ 会显示**(安卓、Linux 上就是如此;iOS 还多一道通知权限)。是否真正显示由系统决定。
+**关于「通知权限」(0.17.0 起)**:设置页在角标开关下面多了一行本机读数(**已授予 / 未授予 / 已被拒绝 / 本机浏览器没有通知能力**)和一个「允许通知」按钮——按钮只在"还没问过"时出现(已授予没什么可问,已被拒绝时浏览器也不会再弹,那一行会直接告诉你去系统设置里改)。它**不是插件的开关**,而是 Apple 的规则:Safari 把角标权限和通知权限绑在一起,程序坞 / 主屏网页应用没被允许通知,`setAppBadge()` 就会被丢掉。**Chrome / Edge 不需要这一步**;申请来的权限只用于画角标,本插件不会发通知。权限在页面外被改动(系统设置里打开/关闭、别的标签页弹过窗)时这一行会自动跟上;刚变成"已授予"的那一刻会立刻把当前数字重设一遍——此前那些调用在没权限时就已经丢了。
+
+设置页里那行「当前环境」只报**本机此刻的事实**(是不是安全上下文、有没有这个 API、是不是已安装的应用),它**不**承诺角标一定会出现——因为**探测到 API ≠ 会显示**(安卓、Linux 上就是如此;WebKit 还多一道通知权限)。是否真正显示由系统决定。
 
 顺便说明两个容易被当成 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)。
+设计取舍(为什么不做通知发送、不做 service worker、为什么不按平台门禁)记在 [`docs/adr/0005-app-icon-badge.md`](./docs/adr/0005-app-icon-badge.md);通知权限这一行(为什么单独探测、为什么不拿它门禁角标调用)记在 [`docs/adr/0009-notification-permission.md`](./docs/adr/0009-notification-permission.md)。
 
 ## 支持的格式
 
@@ -112,7 +127,7 @@ 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` 则每台浏览器按"上次在线时间"重新起基线(不会把历史红点全部点亮)。
+同一个目录里还有三份 JSON:`unread.json`(哪些结束原因算未读)、`unread-seen.json`(已读水位线,`{ version, seen: { 会话id → endAt } }`,上限 400 条、写入是 temp+rename)与 `running.json`(进行中黄点的开关,就一个布尔)。三份都是**可丢的**:删掉 `unread.json` 回到默认规则,删掉 `unread-seen.json` 则每台浏览器按"上次在线时间"重新起基线(不会把历史红点全部点亮),删掉 `running.json` 回到"显示黄点"。**这里不存"进行中"本身**——谁在跑永远是官方宿主的即时事实。
 
 ## 许可证