deepseek-harness-background 0.3.2 → 0.4.1

package/README.md

@@ -36,6 +36,7 @@ The look (fixed wallpaper layer + theme-aware scrim + translucent glass panels d
 - **Fit modes** — `cover` (fill, crop) or `contain` (whole image).
 - **Theme-aware scrim** — the light theme uses a white veil (lifts the art so dark text keeps contrast); the dark theme automatically switches to a black veil (dims the art so light text keeps contrast).
 - **Frosted glass (whitelisted)** — while a background is active, only the surfaces that float as small cards over the wallpaper turn into translucent glass (specular sheen + `backdrop-filter`): the composer card and message bubbles, code blocks / terminal / diff / tool-IO cards / skill & MCP call cards and inline code, the agent task strips and their takeover panels (approval / question / plan review), the chrome buttons (new session, composer plus, scroll-to-bottom), the load-earlier history button, the subagent lineage popover, the sidebar build badge, and the home hero "preview" badge — every glassed surface carries the full recipe (fill + sheen + blur), never translucency without frost. Reading surfaces — dialogs, the settings UI, menus, tooltips, toasts, hover fills and every accent (the send button stays blue) — keep their **official opaque paints** so nothing legible turns washy. The blur radius is driven by the glass-blur slider; `panelOpacity` at 100% restores the official paints on the whitelisted list too.
+- **Third-party glass registry** — any plugin can register its own panels into the same frosted-glass system through the published bridge (`window.__DSH_BACKGROUND_GLASS__` global + the `dsh-background-glass:ready` event): *token* mode adds the missing sheen + blur chain when the panel already fills with an overridden `--dsw-*` token, *fill* mode takes the fill over as well; every rule sits under the `data-dsh-bg-glass` gate so it toggles with the glass automatically. Consumers take zero dependencies and degrade gracefully when this plugin is absent; the whole bridge tears down with it. See [docs/GLASS_API.md](docs/GLASS_API.md).
 - **Conversation timeline** — a DeepSeek-web-style scroll-navigation rail at the right edge of long conversations: one tick per user message on a frosted capsule; hovering expands it into a frosted panel listing every question (active one highlighted in brand blue); clicking jumps the chat to that message. **Key-point bookmarks** — star a question in the expanded panel (persisted per session): marked questions show a golden tick in the collapsed capsule and a "★ marked only" filter narrows the list. Jumps freeze the reading-position tracker until scrolling settles (no mid-jump jitter), and messages withdrawn by a rewind are dropped from the rail automatically. Collapsed and expanded share **one identical height** (no jump); idle ticks are **bottom-pinned** — the newest question's tick hugs the capsule's bottom edge like the official nav, fed by the full-session history regardless of how much of the conversation the chat view has paged in — and the expanded panel's clipped edges get the official **32px fade veils**. While the background glass is on, the rail joins the **same unified glass recipe** as the composer card and bubbles (fill follows panel opacity, blur follows the glass-blur slider); without glass it keeps the official DeepSeek frosted paints. Toggle it off with the timeline switch in the row. If the third-party dsh-chat-timeline plugin is also installed, this rail steps aside instead of doubling it.
 - **Persisted in the official settings document** (`$DSH_HOME/settings.yaml`), waits out restarts.
 - **Clean teardown** — disabling, clearing or uninstalling restores the original background exactly; the plugin only ever removes what it wrote.
@@ -97,6 +98,7 @@ dsh --profile web
 - The plugin's own host routes (`/api/bg-wallpaper/*`: `settings`, `upload`, `image/<id>`) read/write the section and serve uploads with same-origin + size caps + MIME/signature checks + a path-escape fence. A custom route family is used because the api-proxy settings allowlist does not expose third-party namespaces over the settings RPC.
 - The background is drawn as a fixed `z-index:-2` wallpaper layer plus a `z-index:-1` scrim on `body`, toggled by the `data-dsh-bg` attribute; the scrim switches white/black by `data-ds-dark-theme` in the injected stylesheet. Frosted glass is whitelist-scoped: only the whitelisted surfaces get `--dsw-*` surface-token overrides, while everything else is painted by explicit `data-dsh-bg-glass`-gated rules carrying the FULL recipe (fill + sheen + blur chain): the three chrome buttons, the load-earlier history button, the composer dock family (agent task strips TodoPanel / GoalBar / QueueDock and their takeover panels — approval, question, plan review — whose tokens turn translucent and need the blur added), the subagent lineage popover, the home hero preview badge and the sidebar build badge — every other official token and reading surface (menus, dialogs, tooltips, toasts) stays untouched.
 - The **timeline rail** is registered into the `conversation.input.dock` slot (per-session lifecycle) and portals to `body`. Its data comes, fastest first, from a host-side session projection (`bgTimeline`, registered in `src/projection.ts`) that enumerates every user message of the whole session — including turns the conversation has not paged in yet — with the loaded chat-node window as fallback. The conversation's own lazy loading is never driven by the rail (jumping to an old message pages history on demand, exactly like clicking "load earlier"); bookmarks persist in localStorage per session. Idle (collapsed), the tick stack is pinned to the capsule's bottom edge — the newest question's tick always hugs the bottom, older ones clip at the top — matching the official ScrollNav; hovering expands and follows the reading position instead. The official DeepSeek frosted paints are the no-glass fallback — under `data-dsh-bg-glass` the rail joins the plugin's unified recipe (composer fill token + the glass-blur slider chain), exactly like the chrome buttons, code cards and the composer itself.
+- The **third-party glass registry** (`src/client/glass-registry.ts`) publishes its bridge on client apply — before any repaint can race it: `register({ plugin, selectors, mode })` is idempotent per (plugin, mode, selector) triple and synthesizes explicit `body[data-dsh-bg-glass]`-gated recipe rules into a dedicated `<style data-plugin-css>` tag; selectors are structurally validated first (no `{ } ; @ < >`, no backslashes, 500-char cap) with per-selector warn-and-drop that never blocks valid siblings; disposing the client fiber retracts the whole bridge (stylesheet, entries, window key). Contract docs in `docs/GLASS_API.md` / `GLASS_API.zh.md`; behavior locked by `tests/glass-registry.spec.ts`.
 - Uploads live under `$DSH_HOME/deepseek-harness-background/` (content-addressed ids). Switching to a new image or clearing the background deletes the superseded upload file, so the directory does not accumulate dead images in normal use. (An upload that is never saved into the section — e.g. the tab closes right after an upload — can leave one orphaned file behind.) Disable / uninstall leaves nothing behind.
 
 ## Development
@@ -124,6 +126,7 @@ deepseek-harness-background/          # the plugin repo (package name stays the
 │       ├── index.ts          # painter lifecycle + settings row registration
 │       ├── backdrop.ts       # fixed wallpaper layer + scrim + glass surface + preview vars
 │       ├── background-css.ts # injected stylesheet (layers, glass, light/dark scrim, variables)
+│       ├── glass-registry.ts # third-party glass registry (window bridge + gated rule synthesis)
 │       ├── timeline.tsx     # conversation timeline rail (ScrollNav port on the glass system)
 │       ├── timeline-css.ts  # timeline stylesheet (dsbt- prefixed, official metrics)
 │       ├── SettingsRow.tsx   # the General-settings row (preview surface + stepped sliders)

package/README.zh.md

@@ -36,6 +36,7 @@
 - **填充方式** —— `cover`（铺满、裁剪）或 `contain`（完整、留白）。
 - **主题自适应遮罩** —— 浅色主题用白色纱帘（把图片提亮保持深色文字对比度），深色主题自动换成黑色纱帘（压暗图片保持浅色文字对比度）。
 - **毛玻璃（白名单制）** —— 启用背景后，只有以小卡片/小按钮形态悬浮在壁纸上的表面才会变成半透明玻璃（顶部白色高光渐变 + `backdrop-filter`）：输入框卡片与消息气泡、代码块 / 终端 / diff / 工具 IO 卡 / 技能与 MCP 调用卡与行内代码、agent 任务条及其接管面板（审批 / 提问 / 计划评审）、三个铬件按钮（新会话、输入框加号、回到底部）、「加载更早」历史按钮、标题栏展开的子代理列表面板、侧栏构建徽标，以及首页右上角的「预览版」徽标——每块玻璃面都带完整配方（填充 + 高光 + 模糊），绝无"只透明不磨砂"的残缺面。阅读型表面——对话框、设置界面、菜单、Tooltip、Toast、悬停填充与所有强调色（发送键保持品牌蓝）——一律保留**官方不透明样式**，保证可读性。模糊半径由「毛玻璃模糊」滑块驱动；「面板不透明度」调至 100% 时白名单表面也恢复官方原样。
+- **第三方毛玻璃接口** —— 内置毛玻璃注册表（`window.__DSH_BACKGROUND_GLASS__` 全局 + `dsh-background-glass:ready` 事件）：任何插件都可把自家面板的选择器注册进来，套上与内置表面完全一致的配方——`token` 模式为已使用被覆盖 `--dsw-*` 填充的面板补齐高光+模糊链，`fill` 模式连填充一并接管；规则统一挂在 `data-dsh-bg-glass` 门控下随玻璃自动开关。消费方零依赖、未安装本插件时优雅降级，本插件卸载时整桥拆除。详见 [docs/GLASS_API.zh.md](docs/GLASS_API.zh.md)。
 - **会话时间线** —— 长会话右缘的 DeepSeek 官网风格滚动导航轨：毛玻璃胶囊上每条用户消息一枚指示刻度；悬停展开为列出全部提问的毛玻璃面板（当前阅读位置品牌蓝高亮）；点击跳转到对应消息。**重点书签**——展开面板内点击 ★ 标记重点提问（按会话持久化）：已标记项在折叠胶囊上显示金色加宽刻度，「★ 只看标记」一键筛选；跳转期间冻结高亮跟踪（消除中途乱跳），被回退撤回的消息自动从轨道剔除。折叠态与展开态**共用同一高度**（零跳变）；折叠刻度**贴底锚定**——最新提问的横杠始终贴住胶囊底缘（与官网一致），且由全量会话历史驱动、不受对话区分页加载进度影响；展开面板的裁切边缘带官方同款 **32px 淡化渐变**。开启背景毛玻璃后，导航轨与输入框、消息气泡共用**同一套玻璃配方**（透明度随「面板不透明度」、模糊随「毛玻璃模糊」滑块调节，不比其他表面更重）；未开启背景时保持 DeepSeek 官网同款毛玻璃配色。可在设置行内用「会话时间线」开关关闭；若同时安装了第三方 dsh-chat-timeline 插件，本轨道会自动让位避免重叠。
 - **持久化到官方设置文档** —— 存于 `$DSH_HOME/settings.yaml`，跨重启保留。
 - **干净卸载** —— 关闭、清除或卸载后完整恢复原背景；插件只移除自己写过的内容。
@@ -97,6 +98,7 @@ dsh --profile web
 - **会话时间线**注册进 `conversation.input.dock` 槽位（绑定每会话生命周期），portal 渲染到 `body`。数据按速度优先：host 侧会话投影 `bgTimeline`（见 `src/projection.ts`，完整枚举整个会话的全部用户消息——包括对话区尚未分页加载的早期内容），已加载聊天节点窗口作为兜底；轨道从不驱动对话区的懒加载策略（点击旧消息跳转时才按需补页，与点「加载更早」一致）。折叠态刻度列贴底锚定——最新一条提问的横杠始终贴住胶囊底缘、更早的向顶部裁掉，与官网 ScrollNav 一致；悬停展开则改为跟随阅读位置。书签存于 localStorage（按会话隔离）。官网同款毛玻璃配色仅作为未开背景时的兜底：开启玻璃后（`data-dsh-bg-glass`）轨道并入插件统一配方——与输入框一致的 token 填充 + 由「毛玻璃模糊」滑块驱动的同一滤镜链。
 - 插件自有的 host 路由（`/api/bg-wallpaper/*`：`settings`、`upload`、`image/<id>`）负责读写设置与提供上传图片，带同源校验、大小上限、MIME/签名校验与路径穿越防护。使用自定义路由族，是因为 api-proxy 的 settings 白名单不向第三方命名空间开放 settings RPC。
 - 背景以 `body` 上一张固定的 `z-index:-2` 壁纸层 + `z-index:-1` 遮罩绘制，由 `data-dsh-bg` 属性开关；遮罩在注入样式表里按 `data-ds-dark-theme` 切换白/黑纱帘。毛玻璃为白名单制：仅对输入/气泡/代码/任务条等白名单表面覆盖 `--dsw-*` surface token，其余表面通过 `data-dsh-bg-glass` 门控的显式规则补齐整套配方（填充 + 高光 + 模糊滤镜链）：三个 chrome 按钮、「加载更早」历史按钮、composer 坞列家族——agent 任务条（TodoPanel / GoalBar / QueueDock）与接管面板（审批 / 提问 / 计划评审，token 变半透明后由这里补上模糊）、子代理列表弹出层、首页「预览版」徽标、侧栏构建徽章——全部官方 token 与阅读型界面（菜单/对话框/tooltip/toast）保持原样。
+- **第三方玻璃注册表**（`src/client/glass-registry.ts`）：客户端 apply 时即在 `window.__DSH_BACKGROUND_GLASS__` 发布注册 api 并派发 `dsh-background-glass:ready`；`register({ plugin, selectors, mode })` 按 `(plugin, mode, selector)` 三元组幂等登记，把 `body[data-dsh-bg-glass]` 门控的显式配方规则合成进独立的 `<style data-plugin-css>` 标签；选择器先做结构性校验（禁 `{} ; @ < >` 与反斜杠、500 字符上限），违规条目逐条警告并丢弃、不影响兄弟条目；fiber dispose 时整桥拆除（样式表、条目、window 键全清）。契约文档见 `docs/GLASS_API.md` / `GLASS_API.zh.md`，行为由 `tests/glass-registry.spec.ts` 锁定。
 - 上传文件存放在 `$DSH_HOME/deepseek-harness-background/`（内容寻址 id）。切换新图片或清除背景时，被替换的旧上传文件会被自动回收，正常使用下目录不会堆积死图片。（例外：上传后从未保存进设置——例如上传后立刻关闭标签页——会留下一个孤儿文件。）关闭 / 卸载后不留残留。
 
 ## 开发
@@ -124,6 +126,7 @@ deepseek-harness-background/          # 插件仓库（包名保留 npm 风格 i
 │       ├── index.ts          # painter 生命周期 + 设置行注册
 │       ├── backdrop.ts       # 固定壁纸层 + 遮罩 + 玻璃表面 + 预览变量
 │       ├── background-css.ts # 注入的样式表（层、玻璃、明暗遮罩、变量）
+│       ├── glass-registry.ts # 第三方毛玻璃注册表（window 桥 + 门控规则合成）
 │       ├── timeline.tsx      # 会话时间线导航轨（官方 ScrollNav 结构 × 本插件玻璃体系）
 │       ├── timeline-css.ts   # 时间线样式（dsbt- 前缀，官方度量）
 │       ├── SettingsRow.tsx   # 通用设置中的设置行（预览卡 + 阻尼滑块）

package/lib/client.js

@@ -75,7 +75,13 @@ window.__ModuleLoader__.load({
 		*
 		* Selectors target authored attributes (`data-dsh-bg`, `data-composer-card`,
 		* `data-terminal`…), the `:global` `.md-code-block` anchor, and CSS-module
-		* SUFFIX conventions (`_bubble`, `_newSession`…) audited for collisions:
+		* SUFFIX conventions (`_bubble`, `_newSession`…) audited for collisions.
+		*
+		* MAINTENANCE NOTE: the suffix anchors are the host's only stable-enough
+		* integration surface today, but a host restyle that renames them silently
+		* drops the glass. Upgrade path: once the host ships stable data-* anchors
+		* for these surfaces, swap the selector lists below to them and delete the
+		* suffix entries.
 		* `_bubble` excludes `role="tooltip"` (Tooltip.module.css shares the suffix),
 		* `_add` is scoped under `[data-composer-card]` (DiffBlock line markers share
 		* it), `_newSession` excludes `Label` (the button's inner label span) and
@@ -440,6 +446,8 @@ window.__ModuleLoader__.load({
 			observer;
 			active = false;
 			settings;
+			/** Whether the current section resolves to an actual image source. */
+			hasSource = false;
 			savedTokens = /* @__PURE__ */ new Map();
 			savedVars = /* @__PURE__ */ new Map();
 			/** Remember + hijack a property only once so dispose restores the original. */
@@ -468,6 +476,7 @@ window.__ModuleLoader__.load({
 					this.restoreFrameTokens();
 					this.applySurfaceGlass(settings, true);
 					this.active = false;
+					this.hasSource = false;
 					this.removeLayers();
 					document.body.removeAttribute(ACTIVE_ATTR);
 					return;
@@ -483,10 +492,20 @@ window.__ModuleLoader__.load({
 					this.img.className = IMAGE_CLASS;
 					this.img.alt = "";
 					this.img.referrerPolicy = "no-referrer";
+					this.img.onerror = () => {
+						if (this.img === null || this.img.dataset.failed === "1") return;
+						this.img.dataset.failed = "1";
+						this.img.style.visibility = "hidden";
+						console.warn("[deepseek-harness-background] wallpaper image failed to load:", this.img.getAttribute("src"));
+					};
 					this.layer.appendChild(this.img);
 					document.body.appendChild(this.layer);
 				}
-				if (this.img && this.img.getAttribute("src") !== url) this.img.src = url;
+				if (this.img && this.img.getAttribute("src") !== url) {
+					delete this.img.dataset.failed;
+					this.img.style.visibility = "";
+					this.img.src = url;
+				}
 				if (!this.scrim) {
 					this.scrim = document.createElement("div");
 					this.scrim.className = SCRIM_CLASS;
@@ -494,6 +513,7 @@ window.__ModuleLoader__.load({
 				}
 				document.body.setAttribute(ACTIVE_ATTR, "on");
 				this.active = true;
+				this.hasSource = true;
 				document.body.style;
 				this.setVar("--bg-object-fit", settings.fit);
 				this.setVar("--bg-opacity", String(settings.opacity));
@@ -546,6 +566,15 @@ window.__ModuleLoader__.load({
 					case "scrim":
 						this.setVar("--bg-scrim", String(value));
 						break;
+					case "panelOpacity": {
+						const next = {
+							...this.settings,
+							panelOpacity: Number(value)
+						};
+						this.settings = next;
+						this.applySurfaceGlass(next, !this.hasSource);
+						break;
+					}
 					case "blur":
 						this.setVar("--bg-glass-blur", `${value}px`);
 						this.setVar("--bg-glass-saturate", String(glassSaturate(Number(value))));
@@ -688,6 +717,206 @@ window.__ModuleLoader__.load({
 		function clearPreviewSurface(el) {
 			for (const name of PREVIEW_VARS) el.style.removeProperty(name);
 		}
+		/** Property name on window where the api is published. */
+		const GLASS_BRIDGE_GLOBAL = "__DSH_BACKGROUND_GLASS__";
+		/** DOM event announced once the api becomes available (detail = the api). */
+		const GLASS_READY_EVENT = "dsh-background-glass:ready";
+		/** Style-tag dedup key of the registry stylesheet (data-plugin-css). */
+		const REGISTRY_CSS_TAG = "deepseek-harness-background/glass-registry";
+		/** Plugin identity stamped onto the registry <style> element. */
+		const PLUGIN_ID = "deepseek-harness-background";
+		/**
+		* Characters whose presence would let a selector escape its rule context.
+		* ',' is refused too: inside the generated rule body
+		* (`body[gate] <selector> { … }`) a comma lets one registration broaden the
+		* rule to ARBITRARY extra subjects (`.x, html body`) — an unintended
+		* widening of the glass sheet beyond the registered surface. Multiple
+		* surfaces stay supported through the selectors ARRAY.
+		*/
+		const FORBIDDEN_SELECTOR_CHARS = [
+			"{",
+			"}",
+			";",
+			"@",
+			"<",
+			">",
+			","
+		];
+		/** Hard cap on one selector's length (diagnostics-friendly, abuse-proof). */
+		const MAX_SELECTOR_LENGTH = 500;
+		/** Hard cap on selectors per registration call. */
+		const MAX_SELECTORS_PER_SPEC = 64;
+		/**
+		* Validate one raw selector string. Structural checks only: anything that
+		* could escape the generated rule body ({}, ;, @, <, >) is rejected, and a
+		* backslash is refused too (escape sequences have no business in an anchor
+		* selector); ordinary CSS mistakes (a typo'd pseudo-class) are left to the
+		* browser, which drops just that one rule — a safe failure mode.
+		* @returns an error message, or null when the selector is acceptable.
+		*/
+		function selectorProblem(selector) {
+			if (typeof selector !== "string") return "must be a string";
+			const trimmed = selector.trim();
+			if (trimmed === "") return "must not be empty";
+			if (trimmed.length > MAX_SELECTOR_LENGTH) return "exceeds the 500-character limit (" + trimmed.length + ")";
+			for (const ch of FORBIDDEN_SELECTOR_CHARS) if (trimmed.includes(ch)) return "contains a forbidden character (" + JSON.stringify(ch) + ")";
+			if (trimmed.includes(String.fromCharCode(92))) return "contains a backslash (escape sequences are not accepted)";
+			return null;
+		}
+		/** Normalize a spec into validated (plugin, mode, selector) triples.
+		* @returns the accepted triples plus one warning line per rejected selector. */
+		function normalizeSpec(spec) {
+			const plugin = typeof spec?.plugin === "string" && spec.plugin.trim() !== "" ? spec.plugin.trim() : "(anonymous)";
+			const mode = spec?.mode === "fill" ? "fill" : "token";
+			const raw = Array.isArray(spec?.selectors) ? [...spec.selectors] : [spec?.selectors];
+			const rows = [];
+			const warnings = [];
+			if (raw.length > MAX_SELECTORS_PER_SPEC) warnings.push("[glass-registry] " + plugin + ": " + raw.length + " selectors exceeds the 64-selector cap; extra entries dropped.");
+			for (const item of raw.slice(0, MAX_SELECTORS_PER_SPEC)) {
+				const problem = selectorProblem(item);
+				if (typeof item !== "string" || problem !== null) {
+					warnings.push("[glass-registry] " + plugin + ": rejected selector " + JSON.stringify(item) + " — " + (problem ?? "must be a string") + ".");
+					continue;
+				}
+				rows.push({
+					plugin,
+					mode,
+					selector: item.trim()
+				});
+			}
+			return {
+				rows,
+				warnings
+			};
+		}
+		/**
+		* Render one registered surface as a gated CSS rule — the same recipes the
+		* built-in sheets emit for their explicit-fill families.
+		*/
+		function ruleFor(row) {
+			const fill = row.mode === "fill" ? "background-color: var(--dsw-specific-input-major); background-image: linear-gradient(180deg, rgba(255, 255, 255, var(--bg-glass-sheen, 0.07)), rgba(255, 255, 255, var(--bg-glass-sheen-mid, 0.02)) 38%, rgba(255, 255, 255, 0.01)); -webkit-backdrop-filter: blur(var(--bg-glass-blur, 16px)) saturate(var(--bg-glass-saturate, 1.42)) brightness(var(--bg-glass-brightness, 1)) contrast(1.01); backdrop-filter: blur(var(--bg-glass-blur, 16px)) saturate(var(--bg-glass-saturate, 1.42)) brightness(var(--bg-glass-brightness, 1)) contrast(1.01);" : "background-image: linear-gradient(180deg, rgba(255, 255, 255, var(--bg-glass-sheen, 0.07)), rgba(255, 255, 255, var(--bg-glass-sheen-mid, 0.02)) 38%, rgba(255, 255, 255, 0.01)); -webkit-backdrop-filter: blur(var(--bg-glass-blur, 16px)) saturate(var(--bg-glass-saturate, 1.42)) brightness(var(--bg-glass-brightness, 1)) contrast(1.01); backdrop-filter: blur(var(--bg-glass-blur, 16px)) saturate(var(--bg-glass-saturate, 1.42)) brightness(var(--bg-glass-brightness, 1)) contrast(1.01);";
+			return "body[data-dsh-bg-glass] " + row.selector + " { " + fill + " }";
+		}
+		/**
+		* Owns the registered surfaces and the registry stylesheet.
+		*/
+		var GlassRegistry = class {
+			entries = /* @__PURE__ */ new Map();
+			styleEl = null;
+			disposed = false;
+			/**
+			* Register one spec. See BackgroundGlassApi.register.
+			* @param spec - the surfaces to glass.
+			* @returns the unregister function (idempotent).
+			*/
+			register(spec) {
+				if (this.disposed || publishedRegistry !== void 0 && publishedRegistry !== this) {
+					console.warn("[glass-registry] registration ignored: this bridge is no longer the live publication");
+					return () => {};
+				}
+				let normalized;
+				try {
+					normalized = normalizeSpec(spec);
+				} catch (error) {
+					console.warn("[glass-registry] spec rejected: " + (error instanceof Error ? error.message : String(error)));
+					normalized = {
+						rows: [],
+						warnings: []
+					};
+				}
+				const { rows, warnings } = normalized;
+				for (const message of warnings) console.warn(message);
+				const owner = {};
+				const keys = [];
+				for (const row of rows) {
+					const key = JSON.stringify([
+						row.plugin,
+						row.mode,
+						row.selector
+					]);
+					this.entries.set(key, {
+						row,
+						owner
+					});
+					keys.push(key);
+				}
+				this.sync();
+				let unregistered = false;
+				return () => {
+					if (unregistered) return;
+					unregistered = true;
+					for (const key of keys) {
+						const entry = this.entries.get(key);
+						if (entry !== void 0 && entry.owner === owner) this.entries.delete(key);
+					}
+					this.sync();
+				};
+			}
+			/** Rebuild the registry stylesheet from the live entries. */
+			sync() {
+				if (this.entries.size === 0) {
+					this.styleEl?.remove();
+					this.styleEl = null;
+					return;
+				}
+				const seen = /* @__PURE__ */ new Set();
+				const rules = [];
+				for (const { row } of this.entries.values()) {
+					const rule = ruleFor(row);
+					if (!seen.has(rule)) {
+						seen.add(rule);
+						rules.push(rule);
+					}
+				}
+				if (this.styleEl === null) {
+					this.styleEl = document.createElement("style");
+					this.styleEl.dataset.plugin = PLUGIN_ID;
+					this.styleEl.dataset.pluginCss = REGISTRY_CSS_TAG;
+					document.head.appendChild(this.styleEl);
+				}
+				this.styleEl.textContent = rules.join(String.fromCharCode(10));
+			}
+			/** Tear everything down: entries, stylesheet, and the window publication. */
+			dispose() {
+				this.disposed = true;
+				this.entries.clear();
+				this.sync();
+				const w = window;
+				if (w["__DSH_BACKGROUND_GLASS__"] === this.api) delete w[GLASS_BRIDGE_GLOBAL];
+				if (publishedRegistry === this) publishedRegistry = void 0;
+			}
+			/** The published api face over this registry. */
+			api = {
+				version: 1,
+				bridgeId: "deepseek-harness-background",
+				isActive: () => typeof document !== "undefined" && document.body !== null && document.body.hasAttribute("data-dsh-bg-glass"),
+				register: (spec) => this.register(spec)
+			};
+		};
+		/** The registry whose api is CURRENTLY published on window. Module-level on
+		* purpose: the published api face deliberately carries no dispose member
+		* (internal teardown stays unreachable for consumers), so reinstall-time
+		* cleanup needs a handle the window key cannot provide. */
+		let publishedRegistry;
+		/**
+		* Publish the glass registry bridge onto window and announce it. Safe to
+		* call repeatedly: a previous publication's REGISTRY is disposed first, so
+		* exactly one bridge — and one stylesheet — is ever live.
+		* @returns the bridge handle — call .dispose() when this plugin's client
+		*   fiber tears down.
+		*/
+		function installGlassBridge() {
+			publishedRegistry?.dispose();
+			document.querySelector("style[data-plugin-css=\"deepseek-harness-background/glass-registry\"]")?.remove();
+			const registry = new GlassRegistry();
+			publishedRegistry = registry;
+			window[GLASS_BRIDGE_GLOBAL] = registry.api;
+			window.dispatchEvent(new CustomEvent(GLASS_READY_EVENT, { detail: registry.api }));
+			return {
+				api: registry.api,
+				dispose: () => registry.dispose()
+			};
+		}
 		//#endregion
 		//#region src/client/locales.ts
 		/** Chinese copy. */
@@ -724,7 +953,8 @@ window.__ModuleLoader__.load({
 			"timeline.marksOnly": "★ 只看标记",
 			"timeline.mark": "标记为重点",
 			"timeline.unmark": "取消重点标记",
-			"timeline.noMarks": "还没有标记的重点"
+			"timeline.noMarks": "还没有标记的重点",
+			"timeline.cannotJump": "无法跳转：这条历史消息缺少定位信息"
 		};
 		/** English copy. */
 		const en = {
@@ -760,7 +990,8 @@ window.__ModuleLoader__.load({
 			"timeline.marksOnly": "★ Marked only",
 			"timeline.mark": "Mark as key point",
 			"timeline.unmark": "Unmark key point",
-			"timeline.noMarks": "No marked key points"
+			"timeline.noMarks": "No marked key points",
+			"timeline.cannotJump": "Cannot jump: this history message lacks position info"
 		};
 		//#endregion
 		//#region node_modules/.pnpm/clsx@2.1.1/node_modules/clsx/dist/clsx.mjs
@@ -895,41 +1126,41 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var SettingsRow_module_css_default = {
-			"error": "-ozqdq_error",
+			"row": "-ozqdq_row",
+			"segBtn": "-ozqdq_segBtn",
+			"preview": "-ozqdq_preview",
 			"urlRow": "-ozqdq_urlRow",
-			"switch": "-ozqdq_switch",
-			"hint": "-ozqdq_hint",
-			"titleRow": "-ozqdq_titleRow",
-			"clearRow": "-ozqdq_clearRow",
-			"previewGlass": "-ozqdq_previewGlass",
-			"previewEmpty": "-ozqdq_previewEmpty",
-			"sourceRow": "-ozqdq_sourceRow",
-			"urlInput": "-ozqdq_urlInput",
-			"segGroup": "-ozqdq_segGroup",
-			"previewScrim": "-ozqdq_previewScrim",
-			"previewGlassText": "-ozqdq_previewGlassText",
-			"title": "-ozqdq_title",
 			"sliderValue": "-ozqdq_sliderValue",
-			"sliderLabel": "-ozqdq_sliderLabel",
-			"switchKnob": "-ozqdq_switchKnob",
-			"btn": "-ozqdq_btn",
-			"desc": "-ozqdq_desc",
-			"sliderRow": "-ozqdq_sliderRow",
+			"titleRow": "-ozqdq_titleRow",
+			"clearBtn": "-ozqdq_clearBtn",
 			"segRow": "-ozqdq_segRow",
-			"sectionLabel": "-ozqdq_sectionLabel",
 			"enabledBadge": "-ozqdq_enabledBadge",
-			"segActive": "-ozqdq_segActive",
-			"btnDanger": "-ozqdq_btnDanger",
+			"title": "-ozqdq_title",
 			"previewImg": "-ozqdq_previewImg",
-			"segBtn": "-ozqdq_segBtn",
-			"clearBtn": "-ozqdq_clearBtn",
-			"preview": "-ozqdq_preview",
-			"row": "-ozqdq_row",
-			"segLabel": "-ozqdq_segLabel",
 			"header": "-ozqdq_header",
+			"previewGlass": "-ozqdq_previewGlass",
+			"sliderRow": "-ozqdq_sliderRow",
+			"previewGlassText": "-ozqdq_previewGlassText",
 			"slider": "-ozqdq_slider",
+			"switch": "-ozqdq_switch",
+			"sourceRow": "-ozqdq_sourceRow",
+			"clearRow": "-ozqdq_clearRow",
+			"error": "-ozqdq_error",
+			"sliderLabel": "-ozqdq_sliderLabel",
+			"previewScrim": "-ozqdq_previewScrim",
+			"urlInput": "-ozqdq_urlInput",
+			"desc": "-ozqdq_desc",
+			"previewEmpty": "-ozqdq_previewEmpty",
+			"section": "-ozqdq_section",
+			"hint": "-ozqdq_hint",
+			"btn": "-ozqdq_btn",
+			"segGroup": "-ozqdq_segGroup",
+			"segLabel": "-ozqdq_segLabel",
+			"sectionLabel": "-ozqdq_sectionLabel",
 			"btnPrimary": "-ozqdq_btnPrimary",
-			"section": "-ozqdq_section"
+			"segActive": "-ozqdq_segActive",
+			"switchKnob": "-ozqdq_switchKnob",
+			"btnDanger": "-ozqdq_btnDanger"
 		};
 		//#endregion
 		//#region src/client/SettingsRow.tsx
@@ -1128,8 +1359,7 @@ window.__ModuleLoader__.load({
 				};
 				draftRef.current = next;
 				markEditing();
-				if (key === "panelOpacity") paintBackground(next);
-				else paintBackgroundKnob(key, value);
+				paintBackgroundKnob(key, value);
 				if (previewRef.current) paintPreviewSurface(previewRef.current, next);
 			}, [markEditing]);
 			/** Persist one section through the host route and adopt it on success. */
@@ -1137,6 +1367,7 @@ window.__ModuleLoader__.load({
 				dirtyRef.current = true;
 				const result = await settingsClient.save(next);
 				if (result === "failed") {
+					dirtyRef.current = false;
 					setError(t("background.saveFailed"));
 					return;
 				}
@@ -1685,6 +1916,8 @@ window.__ModuleLoader__.load({
     display: flex; align-items: center; justify-content: flex-end;
   }
   .dsbt-jump:focus-visible { outline: 1px solid currentColor; outline-offset: -1px; border-radius: 6px; }
+  .dsbt-jump:disabled { cursor: default; opacity: .55; }
+  .dsbt-jump:disabled .dsbt-title { text-decoration: line-through; text-decoration-color: currentColor; }
   .dsbt-item:hover { color: var(--dsw-alias-label-primary, rgba(0, 0, 0, .95)); }
   body[data-ds-dark-theme] .dsbt-item { color: rgba(255, 255, 255, .65); }
   body[data-ds-dark-theme] .dsbt-item:hover { color: rgba(255, 255, 255, .95); }
@@ -1983,6 +2216,19 @@ window.__ModuleLoader__.load({
 			out.sort((a, b) => a.seq - b.seq);
 			return out;
 		}
+		/**
+		* Count the user messages the loaded window holds WITHOUT collecting or
+		* sorting them — the fast gate railMessages uses to skip the merge path on
+		* the streaming hot path (see there).
+		* @param chat - the loaded chat snapshot.
+		*/
+		function countWindowUserMessages(chat) {
+			const nodes = chat?.nodes;
+			if (nodes === void 0 || typeof nodes.values !== "function") return 0;
+			let count = 0;
+			for (const node of nodes.values()) if (node !== null && typeof node === "object" && node.kind === "user") count += 1;
+			return count;
+		}
 		/** Resolve the DOM anchor key of one entry (direct key form only). */
 		function resolveAnchorKey(m) {
 			return typeof m.key === "string" && m.key !== "" ? m.key : void 0;
@@ -2027,24 +2273,44 @@ window.__ModuleLoader__.load({
 			return out;
 		}
 		/**
-		* Rail messages with the fastest source first: the host projection covers the
-		* WHOLE session (and already excludes rewind cuts), so it wins whenever it
-		* has anything; otherwise fall back to the loaded chat-node window. The
-		* projection path still applies locally-known rewind hiding so a cut lands
-		* instantly even before the next projection push arrives.
-		* @param snapshot - the session conversation snapshot (node fallback).
+		* Rail messages: the host projection (whole-session index) MERGED with the
+		* loaded chat-node window. The projection normally wins outright, but a
+		* projection that lost its baseline (e.g. the plugin was hot-reloaded after
+		* the session's tail page seeded the client store) can miss early entries —
+		* the window fills those gaps whenever it holds them, and window entries
+		* lend their real anchor key to projected entries whose durable id was
+		* absent (early events without one). Locally-known rewind hiding applies to
+		* the merged list so a cut lands instantly, before the next projection push.
+		* @param snapshot - the session conversation snapshot (node window).
 		* @param projected - the raw bgTimeline projection value.
 		*/
 		function railMessages(snapshot, projected) {
 			const projectedMessages = normalizeProjectedTimeline(projected);
-			if (projectedMessages.length > 0) {
-				const chat = snapshot?.chat;
-				const hidden = rewindHiddenSeqsOfChat(chat);
-				const spans = rewindSpansOfChat(chat);
-				if (hidden.size === 0 && spans.length === 0) return projectedMessages;
-				return projectedMessages.filter((m) => !hidden.has(m.seq) && !spans.some((span) => m.seq >= span.start && m.seq <= span.end));
+			const chat = snapshot?.chat;
+			const hidden = rewindHiddenSeqsOfChat(chat);
+			const spans = rewindSpansOfChat(chat);
+			const isHidden = (seq) => hidden.has(seq) || spans.some((span) => seq >= span.start && seq <= span.end);
+			if (projectedMessages.length === 0) return collectMessages(snapshot);
+			const windowUserCount = countWindowUserMessages(chat);
+			const projectionLacksKeys = projectedMessages.some((m) => m.key === void 0);
+			if (windowUserCount <= projectedMessages.length && !projectionLacksKeys) return hidden.size === 0 && spans.length === 0 ? projectedMessages : projectedMessages.filter((m) => !isHidden(m.seq));
+			const windowMessages = collectMessages(snapshot);
+			const bySeq = /* @__PURE__ */ new Map();
+			for (const m of projectedMessages) if (!isHidden(m.seq)) bySeq.set(m.seq, m);
+			for (const m of windowMessages) {
+				if (isHidden(m.seq)) continue;
+				const existing = bySeq.get(m.seq);
+				if (existing === void 0) {
+					bySeq.set(m.seq, m);
+					continue;
+				}
+				if (existing.key === void 0 && m.key !== void 0) bySeq.set(m.seq, {
+					...existing,
+					key: m.key,
+					...existing.text === "" && m.text !== "" ? { text: m.text } : {}
+				});
 			}
-			return collectMessages(snapshot);
+			return [...bySeq.values()].sort((a, b) => a.seq - b.seq);
 		}
 		/**
 		* Outer rail height for a message count: rows + breathing room, clamped so
@@ -2078,26 +2344,70 @@ window.__ModuleLoader__.load({
 			}
 			return Math.round(Math.max(RAIL_MIN_WIDTH, Math.min(RAIL_MAX_WIDTH, widest + 6 + 24 + 16 + 12)));
 		}
-		/** Ensure the target node is loaded, then scroll its row into view. */
-		async function jumpToMessage(sessionsService, sessionId, key) {
+		/** How long one jump may keep paging older history before giving up. */
+		const JUMP_PAGE_DEADLINE_MS = 3e4;
+		/** How long to wait for the chat view to commit the target row. */
+		const JUMP_ROW_WAIT_MS = 3e3;
+		/**
+		* Poll the conversation DOM until the target row is committed. The session
+		* store updates BEFORE React renders the prepended page, so the old one-shot
+		* query right after loadOlder() resolved could miss the row and silently
+		* give up — the reported "click does nothing until the conversation is
+		* nudged (scroll/click)" behavior.
+		* @param key - chat anchor key to look for.
+		* @param timeoutMs - polling budget.
+		*/
+		async function waitForChatRow(key, timeoutMs) {
+			const scrollports = Array.from(document.querySelectorAll("[data-conversation-scroll]"));
+			if (scrollports.length === 0) return null;
+			const selector = `[data-chat-anchor-key="${CSS.escape(key)}"]`;
+			const deadline = Date.now() + timeoutMs;
+			for (;;) {
+				for (const scrollport of scrollports) {
+					const row = scrollport.querySelector(selector);
+					if (row !== null) return row;
+				}
+				if (Date.now() >= deadline) return null;
+				await delay(40);
+			}
+		}
+		/**
+		* Ensure the target node is loaded, wait for the chat view to commit its row
+		* into the DOM, then scroll it into view. Paging uses a time budget instead
+		* of the old fixed 120-iteration guard (each in-flight page burned 50ms of
+		* that guard, so slow history could exhaust it and silently fail).
+		*/
+		async function jumpToMessage(sessionsService, sessionId, key, rowWaitMs = JUMP_ROW_WAIT_MS) {
 			const session = sessionsService.binding(sessionId)?.session;
 			if (session === void 0) return false;
-			let guard = 0;
-			while (guard++ < 120) {
+			const deadline = Date.now() + JUMP_PAGE_DEADLINE_MS;
+			for (;;) {
 				const snapshot = session.getSnapshot();
 				if (snapshot?.chat?.nodes?.get(key) !== void 0) break;
-				if (snapshot?.hasMore !== true) return false;
+				if (snapshot?.hasMore !== true) break;
+				if (Date.now() >= deadline) break;
 				if (snapshot.loadingOlder === true) {
 					await delay(50);
 					continue;
 				}
+				if (snapshot.openState !== void 0 && snapshot.openState !== "open") {
+					await delay(100);
+					continue;
+				}
 				await session.loadOlder();
 			}
-			const row = document.querySelector("[data-conversation-scroll]")?.querySelector(`[data-chat-anchor-key="${CSS.escape(key)}"]`) ?? null;
-			if (row === null) return false;
+			const row = await waitForChatRow(key, rowWaitMs);
+			if (row === null) {
+				console.warn(`[deepseek-harness-background] timeline jump target never rendered: ${key}`);
+				return false;
+			}
 			const reducedMotion = typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 			row.scrollIntoView({
-				behavior: reducedMotion ? "auto" : "smooth",
+				behavior: "auto",
+				block: "center"
+			});
+			if (!reducedMotion) row.scrollIntoView({
+				behavior: "smooth",
 				block: "center"
 			});
 			return true;
@@ -2386,8 +2696,9 @@ window.__ModuleLoader__.load({
 											type: "button",
 											className: "dsbt-jump",
 											ref: isActive ? activeItemRef : void 0,
-											title: `${marked ? "★ " : ""}${m.text === "" ? t("timeline.noText") : m.text}`,
-											"aria-label": `${marked ? "★ " : ""}${t("timeline.roleUser")}: ${m.text.slice(0, 60) || t("timeline.noText")}`,
+											disabled: key === void 0,
+											title: key === void 0 ? t("timeline.cannotJump") : `${marked ? "★ " : ""}${m.text === "" ? t("timeline.noText") : m.text}`,
+											"aria-label": key === void 0 ? `${marked ? "★ " : ""}${t("timeline.roleUser")}: ${t("timeline.cannotJump")}` : `${marked ? "★ " : ""}${t("timeline.roleUser")}: ${m.text.slice(0, 60) || t("timeline.noText")}`,
 											"aria-current": isActive ? "location" : void 0,
 											onClick: () => {
 												if (key === void 0) return;
@@ -2444,6 +2755,7 @@ window.__ModuleLoader__.load({
 		* @param ctx - client cordis context (slots/locale/sessions injected).
 		*/
 		function apply(ctx) {
+			const glassBridge = installGlassBridge();
 			const paint = () => {
 				const snapshot = settingsClient.getSnapshot();
 				const value = snapshot.status === "ready" ? snapshot.value : void 0;
@@ -2474,6 +2786,7 @@ window.__ModuleLoader__.load({
 			}, TimelineRail));
 			ctx.effect(() => () => {
 				unsubscribe();
+				glassBridge.dispose();
 				backgroundPainter.dispose();
 			}, "deepseek-harness-background: background surface");
 		}