dsh-tab-status-light 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Fu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,220 @@
-# Temporary Holding Version
+# dsh-tab-status-light
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Put the AI session state on your browser tab icon** — a plugin for the [DeepSeek Harness](https://github.com/deepseek-ai) Web UI.
+
+[English](#english) · [繁體中文](#繁體中文)
+
+![Tab icon states](preview.png)
+
+---
+
+## English
+
+While a turn runs, the tab icon blinks gray; when the turn finishes it turns green;
+while the session waits for you it turns yellow; when a turn is interrupted it turns red.
+You can tell the state of the agent at a glance — even from another tab — without
+switching back to the app.
+
+| State | Color | Animation | Derived from |
+| --- | --- | --- | --- |
+| Working | gray `#9ca3af` | blinks every 600 ms: **the plain whale** ↔ whale + gray dot (the off half has no dot at all) | `SessionStatus.running === true` |
+| Done | green `#22c55e` | lit for 10 s, then back to the plain whale | a turn **seen running here** whose last `turn/end` reason is not an interruption |
+| Waiting for you | yellow `#eab308` | stays lit until you answer | `SessionStatus.pendingInteraction !== undefined` (question / approval / plan review) |
+| Interrupted | red `#ef4444` | lit for 20 s, then back to the plain whale | a turn **seen running here** whose last `turn/end` reason is `aborted` / `blocked` / `error` / `interrupted` |
+
+The shipped whale is left untouched when no session is selected, when the session has
+not finished a turn yet, or when you merely **switch to a session that finished long ago**
+— green/red are news about something that just happened, not a replay of history.
+`SETTLE_MS` (green, 10 s) and `SETTLE_MS_RED` (red, 20 s) control how long a settled
+badge stays; any new finished turn lights it again.
+
+### Install
+
+The plugin ships as a DSH bundle (`dsh.bundle.patch`). Install it with the harness
+`plugin_manager`:
+
+```js
+plugin_manager({ action: "install_bundle", target: "dsh-tab-status-light" })
+```
+
+Or from the CLI:
+
+```sh
+dsh plugin --profile web add dsh-tab-status-light
+# straight from GitHub instead of npm
+dsh plugin --profile web add github:kyle2241345145351324321/dsh-tab-status-light
+```
+
+Or point at a checkout (handy while developing — edits apply on page reload):
+
+```js
+plugin_manager({ action: "install_bundle", target: "/path/to/dsh-tab-status-light" })
+```
+
+Reload the page (`Cmd+R` / `Ctrl+R`) after installing.
+
+> Requires the harness Web profile with the `@deepseek-ai/dsh-client-ui-session` and
+> `@deepseek-ai/dsh-api-session-controller` client packages available (a standard
+> install has both).
+
+### How it works
+
+- **Pure Client plugin, occupies no slot**: it reads `ctx.sessions.list` (which session
+  is the main view) and `ctx.uiSession.sessionStatus` (running / pending interaction),
+  and follows the session's event source for the newest `turn/end` reason.
+- The icon is **redrawn from the live favicon**: it `fetch()`es the shipped
+  `favicon.svg` / `favicon-dark.svg`, splices one `<circle>` in before `</svg>`, and
+  swaps the `href` of `<link rel="icon">` to a data URL (Chrome repaints the tab icon).
+  The original `href` is restored on teardown.
+- Because of that, the whale artwork is never copied into this plugin — upstream logo
+  changes carry over automatically.
+- Badge geometry inside the shipped 50×50 viewBox: `cx=37, cy=37, r=11, stroke-width=4`;
+  the ring uses the tab background (dark `#35363a`, light `#ffffff`) to separate the dot
+  from the mark.
+- Blinking is driven by a tiny Web Worker, so it **keeps blinking while the tab is in
+  the background** (Chrome throttles page timers in hidden tabs). It falls back to a
+  page timer where workers are unavailable.
+- Both blink halves are precomputed data URLs, so every swap paints on the tick — no
+  file re-read, which is what made the pulse look uneven in earlier versions.
+
+### Tuning
+
+All at the top of [`client.js`](client.js):
+
+| Constant | Default | Meaning |
+| --- | --- | --- |
+| `BADGE` | `{cx:37, cy:37, radius:11, ring:4}` | dot position / radius / ring width |
+| `BADGE_COLOR` | gray / green / yellow / red | state colors |
+| `BLINK_MS` | `600` | blink period while working |
+| `SETTLE_MS` | `10000` | how long the green badge stays |
+| `SETTLE_MS_RED` | `20000` | how long the red badge stays |
+| `RED_TURN_END_KINDS` | `aborted` `blocked` `error` `interrupted` | turn endings that count as interruptions |
+
+### Resource use
+
+Blinking costs about **2 ms of JS per second** (≈0.2 % of one core); when idle it costs
+nothing — no timers, no rescans.
+
+### Known limits
+
+- The icon reflects the **main view** session only; background sessions are not shown.
+- Switching to a session that finished earlier does not flash green (only a turn watched
+  running lights up).
+- Blinking continues in a background tab, but a **frozen** tab (Chrome Memory Saver /
+  battery saver) stops all page JS — no web API can bypass that. To keep it alive, add the
+  origin to `chrome://settings/performance` → "Always keep these sites active".
+  `navigator.wakeLock` does **not** help: it only keeps the screen awake and is released
+  as soon as the page is hidden.
+- When a frozen or backgrounded tab wakes up, the plugin resyncs and repaints immediately,
+  so the icon is always correct when you look at it.
+- It swaps SVG data URLs into `<link rel="icon">`; very old browsers without SVG favicon
+  support will show no change.
+
+### Development
+
+```js
+// this repo *is* the installable bundle — there is no build step
+plugin_manager({ action: "install_bundle", target: "/absolute/path/to/dsh-tab-status-light" })
+```
+
+Edit `client.js`, then reload the page: the Client module is served from disk.
+
+### License
+
+[MIT](LICENSE)
+
+---
+
+## 繁體中文
+
+**把 AI 的狀態畫在瀏覽器分頁圖示上** —— 一個給 DeepSeek Harness Web UI 用的外掛。
+
+AI 在做事時分頁圖示會**灰色一閃一閃**；這一輪完成變**綠**；在等你回答（提問／核准／計畫審查）
+時變**黃**；這一輪被打斷變成**紅**。切到別的分頁也看得到現在是什麼狀態，不用切回來確認。
+
+| 狀態 | 顏色 | 動畫 | 判定依據 |
+| --- | --- | --- | --- |
+| 進行中 | 灰 `#9ca3af` | 每 600 ms 切換：**純鯨魚** ↔ 鯨魚+灰點（暗的那半完全沒有圓點） | `SessionStatus.running === true` |
+| 完成 | 綠 `#22c55e` | 亮 10 秒後回到純鯨魚 | 這一輪**被看到在跑**，且最後一個 `turn/end` 原因不是中斷類 |
+| 等你回答 | 黃 `#eab308` | 一直亮著直到你回答 | `SessionStatus.pendingInteraction !== undefined`（提問／核准／計畫審查） |
+| 中斷 | 紅 `#ef4444` | 亮 20 秒後回到純鯨魚 | 這一輪**被看到在跑**，且最後一個 `turn/end` 原因是 `aborted`／`blocked`／`error`／`interrupted` |
+
+沒選 session、該 session 還沒跑完任何一輪、或只是**切到一個早就結束的 session** 時，
+不會動原本的鯨魚圖示 —— 綠／紅是「剛剛發生的事」的通知，不會把歷史重播一次。
+綠燈停留由 `SETTLE_MS`（10 秒）控制、紅燈由 `SETTLE_MS_RED`（20 秒）控制，
+任何新的一輪結束都會讓燈重新亮起。
+
+### 安裝
+
+外掛以 DSH bundle 形式發佈（`dsh.bundle.patch`），用 harness 的 `plugin_manager` 安裝：
+
+```js
+plugin_manager({ action: "install_bundle", target: "dsh-tab-status-light" })
+```
+
+或用 CLI：
+
+```sh
+dsh plugin --profile web add dsh-tab-status-light
+# 也可以直接從 GitHub 安裝（不走 npm）
+dsh plugin --profile web add github:kyle2241345145351324321/dsh-tab-status-light
+```
+
+開發時直接指到資料夾（改檔後重新整理就生效）：
+
+```js
+plugin_manager({ action: "install_bundle", target: "/path/to/dsh-tab-status-light" })
+```
+
+安裝後重新整理頁面（`Cmd+R`／`Ctrl+R`）。
+
+> 需要 harness 的 Web profile，且具備 `@deepseek-ai/dsh-client-ui-session` 與
+> `@deepseek-ai/dsh-api-session-controller` 這兩個 Client 套件（標準安裝即有）。
+
+### 運作方式
+
+- **純 Client 外掛、不佔用任何 slot**：讀 `ctx.sessions.list`（哪個 session 是主視窗）與
+  `ctx.uiSession.sessionStatus`（running／pendingInteraction），並訂閱該 session 的
+  event source 取得最新的 `turn/end` 原因。
+- 圖示是**即時重繪**的：`fetch()` 原本的 `favicon.svg`／`favicon-dark.svg`，在 `</svg>`
+  前插入一顆 `<circle>`，把 `<link rel="icon">` 的 `href` 換成 data URL（Chrome 會跟著
+  重畫分頁圖示），unmount 時還原原始 `href`。
+- 因此鯨魚圖案不會被複製一份到外掛裡，上游換 logo 也會自動跟上。
+- 圓點幾何（50×50 viewBox 內）：`cx=37, cy=37, r=11, stroke-width=4`；
+  外圈用分頁底色（深色 `#35363a`、淺色 `#ffffff`）把圓點跟鯨魚隔開。
+- 閃爍由一個小型 Web Worker 計時，**分頁切到背景仍會閃**（Chrome 會節流隱藏分頁的
+  頁面計時器）；不支援 Worker 時自動退回頁面計時器。
+- 閃爍的兩幀都是預先算好的 data URL，所以每一次切換都在節拍上完成 —— 早期版本會回去
+  讀原始圖檔，那一幀就會慢半拍，看起來忽長忽短。
+
+### 可調參數
+
+都在 [`client.js`](client.js) 檔頭（`BADGE`、`BADGE_COLOR`、`BLINK_MS`、`SETTLE_MS`、
+`SETTLE_MS_RED`、`RED_TURN_END_KINDS`），說明同上表。
+
+### 資源用量
+
+閃爍中約 **2 ms JS／秒**（單核約 0.2%）；閒置時 0（沒有計時器、沒有重新掃描）。
+
+### 已知限制
+
+- 圖示只反映**主視窗**那個 session；其他背景 session 不會顯示。
+- 切換到「早就跑完」的 session 不會亮綠燈（只亮真的看到跑完的那一輪）。
+- 分頁在背景仍會閃；但被**凍結**（Chrome Memory Saver／省電模式）時任何網頁的 JS 都會停，
+  沒有 API 可以繞過。想讓它一直閃，把網址加進 `chrome://settings/performance` →
+  「永遠讓這些網站保持運作」。`navigator.wakeLock` **沒有用**：它只防螢幕休眠，分頁一隱藏就被釋放。
+- 分頁解凍／切回前景時會立刻重新同步並重畫，所以看到的時候一定是正確狀態。
+- 用 SVG data URL 換 `href`，不支援 SVG favicon 的舊瀏覽器看不到變化。
+
+### 開發
+
+```js
+// 這個 repo 就是可直接安裝的 bundle，沒有 build step
+plugin_manager({ action: "install_bundle", target: "/absolute/path/to/dsh-tab-status-light" })
+```
+
+改完 `client.js` 後在瀏覽器重新載入頁面即可生效（Client 模組是即時從磁碟供應的）。
+
+### License
+
+[MIT](LICENSE)

package/client.js

@@ -0,0 +1,442 @@
+/**
+ * Tab status light.
+ *
+ * The browser tab icon is the page logo the user watches while a turn runs, so
+ * this bundle paints the AI session state onto it:
+ *
+ * - gray, blinking: the main session is running a turn. The dark half of the
+ *   blink is the untouched shipped logo, so the tab pulses between "mark" and
+ *   "mark + dot" instead of fading a dot in and out.
+ * - yellow: the session is waiting for the user (question, approval, plan review);
+ *   stays lit until the user answers.
+ * - green: the last turn finished normally.
+ * - red: the last turn was aborted, blocked, errored, or crash-interrupted.
+ * - settled states fade back to the untouched logo after `SETTLE_MS` (green) or
+ *   `SETTLE_MS_RED` (red) without new activity, so a finished tab stops advertising.
+ * - opening a session that merely *had* finished earlier shows nothing: a settled
+ *   badge is only painted for a turn this plugin actually watched run.
+ *
+ * State comes from the Client services that already own it: the main view's
+ * identity from the Session list (`retainedBy.mainView`), running and pending
+ * interaction from `uiSession.sessionStatus`, and the closing turn's reason from
+ * the session event window's newest `turn/end`. A favicon has no slot, so the
+ * shipped `link[rel~="icon"]` elements are the one thing this plugin edits
+ * outside a component; their original `href` values are restored on teardown.
+ */
+window.__ModuleLoader__.load({
+	id: "dsh-tab-status-light",
+	factory: () => {
+		/** State -> badge color. Icon artwork is the one place literal colors are correct: an SVG favicon document cannot read page theme tokens. */
+		const BADGE_COLOR = {
+			working: "#9ca3af",
+			asking: "#eab308",
+			done: "#22c55e",
+			interrupted: "#ef4444"
+		};
+		/** Turn endings that must read as "interrupted" rather than "done". */
+		const RED_TURN_END_KINDS = new Set(["aborted", "blocked", "error", "interrupted"]);
+		/** Badge geometry inside the shipped 50x50 favicon viewBox (bottom-right corner). */
+		const BADGE = { cx: 37, cy: 37, radius: 11, ring: 4 };
+		/** Ring color per browser theme: separates the badge from the monochrome mark on either tab background. */
+		const RING = { dark: "#35363a", light: "#ffffff" };
+		/** Blink period: the icon alternates between the shipped logo and the logo with the gray dot. */
+		const BLINK_MS = 600;
+		/** How long a green (turn finished) badge stays before the tab returns to the plain logo. */
+		const SETTLE_MS = 10000;
+		/** Same for red: an interruption is louder news, so it stays on the tab longer. */
+		const SETTLE_MS_RED = 20000;
+		/**
+		 * Blink half that shows the bare mark. It is painted from a cached data URL
+		 * rather than restored to the shipped `href`: swapping back to the file URL
+		 * makes Chrome re-read the icon file, which lands a beat late and made the
+		 * blink look uneven.
+		 */
+		const PLAIN = "\u0000plain";
+		const SVG_CLOSE = "</svg>";
+		/**
+		 * Blink driver source. Chrome throttles page timers in hidden tabs (down to one
+		 * tick per minute under intensive throttling), which freezes the blink exactly
+		 * when the user is looking at another tab — the case this light exists for. A
+		 * dedicated Worker keeps its own timer outside that throttling.
+		 */
+		const TICKER_SOURCE = "let h=null;onmessage=(e)=>{const ms=e.data;if(h!==null){clearInterval(h);h=null}if(ms>0)h=setInterval(()=>postMessage(0),ms)};";
+
+		/**
+		 * Interval that keeps ticking while the tab is in the background.
+		 * @param ms - tick period.
+		 * @param onTick - called once per tick.
+		 * @returns a disposer.
+		 */
+		function startTicker(ms, onTick) {
+			try {
+				const url = URL.createObjectURL(new Blob([TICKER_SOURCE], { type: "text/javascript" }));
+				const worker = new Worker(url);
+				URL.revokeObjectURL(url);
+				worker.onmessage = () => onTick();
+				worker.postMessage(ms);
+				return () => {
+					worker.onmessage = null;
+					worker.postMessage(0);
+					worker.terminate();
+				};
+			} catch {
+				// No Worker/Blob in this environment: the page timer still works in the
+				// foreground, the browser just throttles it once the tab is hidden.
+				const timer = globalThis.setInterval(onTick, ms);
+				return () => globalThis.clearInterval(timer);
+			}
+		}
+
+		/**
+		 * Wrap one SVG document in a base64 data URL. The favicon art is ASCII, so
+		 * encoding is lossless.
+		 * @param svg - complete SVG document text.
+		 * @returns a `data:` URL the favicon link accepts.
+		 */
+		function toDataUrl(svg) {
+			return "data:image/svg+xml;base64," + btoa(unescape(encodeURIComponent(svg)));
+		}
+
+		/**
+		 * Badge markup for one state.
+		 * @param state - one of `BADGE_COLOR`'s keys.
+		 * @param ring - ring color for the surrounding browser theme.
+		 * @returns the SVG circle element.
+		 */
+		function badgeMarkup(state, ring) {
+			return '<circle cx="' + BADGE.cx + '" cy="' + BADGE.cy + '" r="' + BADGE.radius +
+				'" fill="' + BADGE_COLOR[state] +
+				'" stroke="' + ring + '" stroke-width="' + BADGE.ring + '"/>';
+		}
+
+		/**
+		 * Owns the tab icons: reads the shipped icon documents once, derives one
+		 * data URL per theme/state, and restores the shipped icons when the plugin
+		 * unloads.
+		 */
+		function createIconPainter() {
+			let frames = null;
+			let wantedState;
+			let disposed = false;
+			const cache = new Map();
+
+			const reading = (async () => {
+				const links = Array.from(document.head.querySelectorAll('link[rel~="icon"]'));
+				const loaded = [];
+				for (const link of links) {
+					const media = link.getAttribute("media") ?? "";
+					const frame = {
+						link,
+						original: link.getAttribute("href"),
+						theme: /dark/i.test(media) ? "dark" : "light",
+						art: null
+					};
+					try {
+						const response = await fetch(link.href);
+						if (response.ok) {
+							const text = await response.text();
+							const end = text.lastIndexOf(SVG_CLOSE);
+							if (text.includes("<svg") && end > 0) frame.art = text.slice(0, end);
+						}
+					} catch {
+						// A failed read keeps the plain-badge fallback.
+					}
+					loaded.push(frame);
+				}
+				return loaded;
+			})().catch(() => []);
+
+			/**
+			 * Data URL for one frame's current state.
+			 * @param frame - one shipped icon slot.
+			 * @param state - badge state.
+			 * @returns the icon URL.
+			 */
+			function hrefFor(frame, state) {
+				const key = frame.theme + "|" + (state === PLAIN ? "bare" : state) + "|" + (frame.art === null ? "plain" : "brand");
+				const cached = cache.get(key);
+				if (cached !== undefined) return cached;
+				const badge = state === PLAIN ? "" : badgeMarkup(state, RING[frame.theme]);
+				const svg = frame.art === null
+					? '<svg xmlns="http://www.w3.org/2000/svg" width="50" height="50" viewBox="0 0 50 50">' + badge + SVG_CLOSE
+					: frame.art + badge + SVG_CLOSE;
+				const href = toDataUrl(svg);
+				cache.set(key, href);
+				return href;
+			}
+
+			/** Write the wanted state onto every shipped icon link. */
+			function paint() {
+				if (disposed || frames === null) return;
+				for (const frame of frames) {
+					const href = wantedState === undefined
+						? frame.original
+						: hrefFor(frame, wantedState === PLAIN ? PLAIN : wantedState);
+					if (href === null || frame.link.getAttribute("href") === href) continue;
+					frame.link.setAttribute("href", href);
+				}
+			}
+
+			return {
+				/** Begin reading the shipped icons and paint the wanted state afterwards. */
+				start() {
+					reading.then((loaded) => {
+						if (disposed) return;
+						frames = loaded;
+						paint();
+					});
+				},
+				/**
+				 * Request one visual state.
+				 * @param state - badge state, or undefined for the untouched shipped icon.
+				 */
+				set(state) {
+					wantedState = state;
+					paint();
+				},
+				/** Restore every shipped icon and drop derived URLs. */
+				dispose() {
+					disposed = true;
+					if (frames !== null) {
+						for (const frame of frames) {
+							if (frame.original !== null) frame.link.setAttribute("href", frame.original);
+						}
+					}
+					cache.clear();
+				}
+			};
+		}
+
+		/**
+		 * Tracks the main session's state and drives the painter.
+		 * @param ctx - the Client root context.
+		 * @param painter - icon painter owned by the same effect.
+		 */
+		function createStatusLight(ctx, painter) {
+			let mainId;
+			let binding;
+			let stopEvents;
+			let turnEndKind;
+			/** Sentinel that forces the next {@link apply} to repaint even when nothing moved. */
+			const STALE = "\u0000stale";
+			let appliedState;
+			let appliedActivity = -1;
+			/** Bumped whenever something actually happens (new turn end, session switch), so a faded badge can come back. */
+			let activity = 0;
+			let stopBlink;
+			let stopSettle;
+			/**
+			 * Whether a turn has actually been seen running since this session was bound.
+			 * A finished session that is merely opened must stay quiet: green/red are news
+			 * about a turn the user watched, not a status replayed from history.
+			 */
+			let sawRunning = false;
+
+			/** Drop both timers (blink and settle). */
+			function stopTimers() {
+				if (stopBlink !== undefined) {
+					stopBlink();
+					stopBlink = undefined;
+				}
+				if (stopSettle !== undefined) {
+					stopSettle();
+					stopSettle = undefined;
+				}
+			}
+
+			/**
+			 * Newest `turn/end` reason in the session event window.
+			 * @param source - the Session's event source.
+			 * @returns the reason kind, or undefined before any turn closed.
+			 */
+			function readTurnEndKind(source) {
+				const entries = source.getSnapshot().entries;
+				for (let index = entries.length - 1; index >= 0; index -= 1) {
+					const entry = entries[index];
+					if (entry.type === "event" && entry.event.type === "turn/end") return entry.event.data.reason.kind;
+				}
+				return undefined;
+			}
+
+			/**
+			 * Session currently shown in the conversation view.
+			 * @returns its identity, or undefined while no session is selected.
+			 */
+			function readMainId() {
+				const list = ctx.sessions.list.getSnapshot();
+				for (const id of list.ids) {
+					const row = list.byId[id];
+					if (row !== undefined && row.retainedBy !== undefined && row.retainedBy.mainView !== undefined) return id;
+				}
+				return undefined;
+			}
+
+			/** The one state the icon should show right now. */
+			function readState() {
+				if (mainId === undefined) return undefined;
+				const status = ctx.uiSession.sessionStatus.getSnapshot().get(mainId);
+				if (status !== undefined) {
+					if (status.pendingInteraction !== undefined) return "asking";
+					if (status.running === true) return "working";
+				}
+				// Only a turn this plugin watched run may leave a settled badge behind.
+				if (turnEndKind === undefined || !sawRunning) return undefined;
+				return RED_TURN_END_KINDS.has(turnEndKind) ? "interrupted" : "done";
+			}
+
+			/**
+			 * Paint the current state. Re-paints only when the state or the activity
+			 * token moved, so a settled badge that faded to the plain logo stays faded
+			 * until something new happens.
+			 */
+			function apply() {
+				const state = readState();
+				if (state === appliedState && activity === appliedActivity) return;
+				appliedState = state;
+				appliedActivity = activity;
+				stopTimers();
+				if (state === undefined) {
+					painter.set(undefined);
+					return;
+				}
+				if (state === "working") {
+					// Blink between the untouched logo and the logo carrying the dot:
+					// the "off" half is the shipped mark, not a dimmed dot.
+					let lit = true;
+					painter.set(state);
+					stopBlink = startTicker(BLINK_MS, () => {
+						lit = !lit;
+						// Both halves are cached data URLs, so every swap paints on the tick.
+						painter.set(lit ? state : PLAIN);
+					});
+					return;
+				}
+				painter.set(state);
+				if (state === "asking") return;
+				// A settled badge is news, not a permanent decoration: let the tab go back
+				// to the plain logo once nothing new has happened for a while. Interruptions
+				// stay longer than completions.
+				const timer = globalThis.setTimeout(() => {
+					stopSettle = undefined;
+					painter.set(undefined);
+				}, state === "interrupted" ? SETTLE_MS_RED : SETTLE_MS);
+				stopSettle = () => globalThis.clearTimeout(timer);
+			}
+
+			/**
+			 * Observe the newest `turn/end` of the bound session.
+			 * @param source - the binding's event source.
+			 */
+			function watchEvents(source) {
+				stopEvents = source.subscribe((window) => {
+					const change = window.change;
+					if (change.kind === "append") {
+						for (let index = change.entries.length - 1; index >= 0; index -= 1) {
+							const entry = change.entries[index];
+							if (entry.type === "event" && entry.event.type === "turn/end") {
+								turnEndKind = entry.event.data.reason.kind;
+								activity += 1;
+								apply();
+								return;
+							}
+						}
+						return;
+					}
+					if (change.kind === "replace") {
+						turnEndKind = readTurnEndKind(source);
+						apply();
+					}
+				});
+			}
+
+			/** Re-bind to the main session when identity or generation changed, then paint. */
+			function sync() {
+				const nextId = readMainId();
+				const nextBinding = nextId === undefined ? undefined : ctx.sessions.binding(nextId);
+				/** A switch to another session is a switch; a new binding generation for the same session is not. */
+				const switched = nextId !== mainId;
+				if (switched || nextBinding !== binding) {
+					mainId = nextId;
+					binding = nextBinding;
+					if (stopEvents !== undefined) {
+						stopEvents();
+						stopEvents = undefined;
+					}
+					if (switched) {
+						activity += 1;
+						turnEndKind = undefined;
+						// Opening a session is not an event: its already-finished history must not
+						// flash a green/red badge. Only a turn seen running here may settle.
+						sawRunning = false;
+					}
+					if (nextBinding !== undefined) {
+						// Subscribe before the scan below: a window that replaced its entries
+						// before this moment would never deliver a change callback afterwards.
+						watchEvents(nextBinding.eventSource);
+					}
+				}
+				if (mainId !== undefined) {
+					const status = ctx.uiSession.sessionStatus.getSnapshot().get(mainId);
+					if (status !== undefined && status.running === true) sawRunning = true;
+				}
+				// Always rescan: a turn that closed while the stream was silent (or while no
+				// subscription was in place yet) is only visible in the window itself.
+				turnEndKind = nextBinding === undefined ? undefined : readTurnEndKind(nextBinding.eventSource);
+				apply();
+			}
+
+			/**
+			 * A frozen, discarded or restored tab may have lost the blink tick or kept a
+			 * stale frame: re-derive everything and repaint even when the computed state
+			 * did not move.
+			 */
+			function wake() {
+				if (document.visibilityState === "hidden") return;
+				appliedState = STALE;
+				sync();
+			}
+
+			return {
+				/** Install the subscriptions; call from the owning effect. */
+				start() {
+					const stopList = ctx.sessions.list.subscribe(sync);
+					const stopStatus = ctx.uiSession.sessionStatus.subscribe(sync);
+					document.addEventListener("resume", wake);
+					document.addEventListener("pageshow", wake);
+					document.addEventListener("visibilitychange", wake);
+					sync();
+					return () => {
+						stopList();
+						stopStatus();
+						document.removeEventListener("resume", wake);
+						document.removeEventListener("pageshow", wake);
+						document.removeEventListener("visibilitychange", wake);
+						if (stopEvents !== undefined) stopEvents();
+						stopTimers();
+						stopEvents = undefined;
+					};
+				}
+			};
+		}
+
+		return {
+			inject: ["sessions", "uiSession"],
+			/**
+			 * Start the tab status light.
+			 * @param ctx - the Client root context.
+			 */
+			apply(ctx) {
+				const painter = createIconPainter();
+				const light = createStatusLight(ctx, painter);
+				ctx.effect(() => {
+					painter.start();
+					const stopLight = light.start();
+					return () => {
+						stopLight();
+						painter.dispose();
+					};
+				}, "tab-status-light: main session state");
+			}
+		};
+	}
+});

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: tab-status-light
+      name: 'dsh-tab-status-light'

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Tab status light">
+  <rect width="64" height="64" rx="14" fill="#16181d"/>
+  <circle cx="32" cy="18" r="6" fill="#9ca3af"/>
+  <circle cx="17" cy="41" r="6" fill="#22c55e"/>
+  <circle cx="47" cy="41" r="6" fill="#eab308"/>
+  <circle cx="32" cy="52" r="6" fill="#ef4444"/>
+</svg>

package/index.js

@@ -0,0 +1,6 @@
+/**
+ * Host half of the tab status light bundle. Every fact this bundle needs
+ * (session list, session status, turn end reasons) already reaches the Client,
+ * so the Host contributes nothing.
+ */
+export function apply() {}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Tab Status Light",
+    "description": "Puts the AI session state on the browser tab icon: gray pulsing while working, green when done, yellow while it waits for your answer, red when the turn is interrupted."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "分頁狀態燈",
+    "description": "在瀏覽器分頁圖示上顯示 AI 狀態：處理中灰燈閃爍、完成綠燈、等待你回答黃燈、被打斷紅燈。"
+  }
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "dsh-tab-status-light",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Show the AI session state on the browser tab icon — gray blinking while working, green when done, yellow while it waits for your answer, red when interrupted. 把 AI 狀態畫在分頁圖示上：進行中灰燈閃爍、完成綠、等你回答黃、中斷紅。",
+  "license": "MIT",
+  "author": "Kyle Fu",
+  "keywords": [
+    "deepseek",
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "favicon",
+    "tab-icon",
+    "status"
+  ],
+  "homepage": "https://github.com/kyle2241345145351324321/dsh-tab-status-light#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kyle2241345145351324321/dsh-tab-status-light.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kyle2241345145351324321/dsh-tab-status-light/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "preview.png",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-api-session-controller"
+      ]
+    }
+  }
+}