deepseek-harness-background 0.5.1 → 0.5.2

package/README.md

@@ -50,9 +50,9 @@ The look (fixed wallpaper layer + theme-aware scrim + translucent glass panels d
 - **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 one documented exception: the turn rail's hover preview, which is rail chrome over the art and joins the glass sheet). 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** — the DeepSeek-web turn-navigation rail at the right edge of long conversations, one tick per question, with a hover/focus preview of that turn's prompt. Two frontends, one backend, chosen by what the running kernel supports:
-  - **dsh ≥ 0.1.2 (enhancement)** — the kernel ships this rail already, so the plugin renders nothing of its own and only fixes its behaviour: clicks become a **smooth glide** instead of the stock instant jump (ease-in-out, distance-paced, cancelled the moment the reader scrolls, `prefers-reduced-motion` places directly), and reaching for the rail pages older history in so turns behind "load earlier" get a tick and become reachable — stopping at the rail's own uncompressed capacity, past which the official stylesheet would squeeze the marks into an unaimable bar. Because the official hover preview card paints an opaque fill, it joins the glass sheet under the wallpaper gate instead (same explicit-fill recipe as the composer card, driven by the glass-blur slider). The rail's active-mark state stays the kernel's own — the glide scrolls the real scrollport, so the stock scroll handler keeps updating it and the persisted scroll position.
+  - **dsh ≥ 0.1.2 (enhancement)** — the kernel ships this rail already, so the plugin renders nothing of its own and only fixes its behaviour, scoped to what the running rail still lacks (a capability check on the rail's own published metrics, never a version compare). Clicks on a **loaded** mark become a **smooth glide** instead of the stock instant jump (ease-in-out, distance-paced, cancelled the moment the reader scrolls, `prefers-reduced-motion` places directly). On **0.1.2-alpha.1/2** the rail lists only loaded turns, so reaching for it also pages older history in — turns behind "load earlier" get a tick and become reachable, stopping at the rail's own uncompressed capacity, past which the official stylesheet would squeeze the marks into an unaimable bar. On **0.1.2-alpha.3+** the official rail rebuilt itself (fixed-pitch marks scrolling inside a frame, fed by the whole-log turn outline: every turn renders, unloaded ones page on demand), so the plugin narrows to the smooth glide alone — click indexes are resolved against the same merged ladder the kernel renders, marks outside the loaded window are left to the kernel's own jump, and the warm-up does not run. Because the official hover preview card paints an opaque fill, it joins the glass sheet under the wallpaper gate instead (same explicit-fill recipe as the composer card, driven by the glass-blur slider). The rail's active-mark state stays the kernel's own — the glide scrolls the real scrollport, so the stock scroll handler keeps updating it and the persisted scroll position.
   - **dsh ≤ 0.1.1 (ported rail)** — no official rail exists, so the plugin renders its own port of it (identical metrics, plus the same glass treatment), fed by the same backend.
-  In both cases the bottom-follow state is detached one frame before the glide (streaming growth / turn-end re-renders cannot yank it back to the floor), messages withdrawn by a rewind are dropped automatically (the target parser accepts `seq 42` / `#42` / english-chinese verb forms plus structured fields, and recognizes third-party `data-dsh-rewind-hidden` node markers), and history paging compensates the prepended height so the reader's view never moves. Toggle it off with the timeline switch in the row.
+  In both cases the bottom-follow state is detached one frame before the glide (streaming growth / turn-end re-renders cannot yank it back to the floor), messages withdrawn by a rewind are dropped automatically (the target parser accepts `seq 42` / `#42` / english-chinese verb forms plus structured fields, and recognizes third-party `data-dsh-rewind-hidden` node markers), and wherever this plugin pages history itself (the ported rail and the alpha.1/2 rail) every page compensates the prepended height so the reader's view never moves. Toggle it off with the timeline switch in the row.
 - **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.
 
@@ -103,7 +103,7 @@ dsh --profile web
 | 毛玻璃模糊 / Glass blur | `0..40px` `backdrop-filter` blur on the translucent surfaces (1px steps). |
 | 壁纸模糊 / Wallpaper blur | `0..60px` blur of the wallpaper image itself (2px steps). |
 | 填充方式 / Fit | `cover` or `contain`. |
-| 会话时间线 / Timeline | on/off switch for the conversation timeline (default on). On dsh ≥ 0.1.2 the row is labelled 会话时间线增强 / *enhancement*: the official rail stays and this only improves its behaviour; turning it off restores stock behaviour. On older kernels the row is 会话时间线 / *timeline* and the switch controls the plugin's own ported rail. |
+| 会话时间线 / Timeline | on/off switch for the conversation timeline (default on). On dsh ≥ 0.1.2 the row is labelled 会话时间线增强 / *enhancement*: the official rail stays and this only improves its behaviour; turning it off restores stock behaviour. The copy follows the kernel generation — full enhancement on alpha.1/2, smooth-jump-only on alpha.3+. On older kernels the row is 会话时间线 / *timeline* and the switch controls the plugin's own ported rail. |
 
 5. **清除背景** removes the background and restores the stock look.
 
@@ -112,7 +112,7 @@ dsh --profile web
 - The **settings row** lives in the official General settings section (`settings.general.item` slot), next to the Appearance row. Its chrome uses only `--dsw-alias-*` design tokens (buttons / pills / segmented control / slider track match the official shell); sliders are native `input[type=range]` with 5% / 1–2px steps and release-commit.
 - 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** is registered into the `conversation.input.dock` slot (per-session lifecycle). Mode detection is a capability check on the slot props rather than a version compare: the official rail is rendered from the very index `ui-chat` publishes as a session hook (`useChat(s => s.navigation.items())`, dsh >= 0.1.2), so the presence of that hook *is* the presence of the official rail — and it survives pre-releases, forks and deployments that mount a different conversation target. With the hook the plugin renders nothing and intercepts the official rail clicks in the **capture** phase (React 18 dispatches `onClick` from the root container during the bubble phase, so a capture listener on the rail runs first and `stopImmediatePropagation()` keeps the stock handler from ever firing); without it the plugin renders its own port of the rail, portaled to `body`. Both run the same jump engine. 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; that window is read duck-typed across both kernel generations, because 0.1.2 moved the Chat snapshot from `session.getSnapshot().chat` to `useChat()`, the one breaking change for this plugin. History warm-up runs only when the reader reaches for the rail and stops at the rail uncompressed tick capacity (`floor((height - 12) / 10) + 1`); every page compensates the prepended height, because the host own prepend anchor is unreachable from outside. The ported rail carries the same **glass treatment as the enhanced official one** — the hover preview joins the frosted-glass sheet under the wallpaper gate (same explicit-fill recipe as the composer card) — so both frontends look identical to the reader.
+- The **timeline** is registered into the `conversation.input.dock` slot (per-session lifecycle). Mode detection is a capability check on the slot props rather than a version compare: the official rail is rendered from the very index `ui-chat` publishes as a session hook (`useChat(s => s.navigation.items())`, dsh >= 0.1.2), so the presence of that hook *is* the presence of the official rail — and it survives pre-releases, forks and deployments that mount a different conversation target. With the hook the plugin renders nothing and intercepts the official rail clicks in the **capture** phase (React 18 dispatches `onClick` from the root container during the bubble phase, so a capture listener on the rail runs first and `stopImmediatePropagation()` keeps the stock handler from ever firing) — resolving the click index against the ladder the kernel actually renders: the loaded items alone on the compressing alpha.1/2 rail, and on the alpha.3 frame-style rail the same outline-plus-loaded merge the kernel renders, with marks outside the loaded window (no anchor key) left to the kernel's own load-through jump — and while one of those kernel jumps is still paging (a mark pulses `aria-busy`) the plugin stands down entirely, because the kernel's loaded branch cancels its own pending jump before landing and an interception would bypass that cancellation; without the hook the plugin renders its own port of the rail, portaled to `body`. Both run the same jump engine. 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; that window is read duck-typed across both kernel generations, because 0.1.2 moved the Chat snapshot from `session.getSnapshot().chat` to `useChat()`, the one breaking change for this plugin. History warm-up runs only when the reader reaches for the rail — and only where it is still wanted: the compressing alpha.1/2 rail and the ported one, stopping at the rail uncompressed tick capacity (`floor((height - 12) / 10) + 1`); the alpha.3 frame-style rail lists every turn already and pages on demand itself, so warming would only fight the kernel's pager. Every page compensates the prepended height, because the host own prepend anchor is unreachable from outside. The ported rail carries the same **glass treatment as the enhanced official one** — the hover preview joins the frosted-glass sheet under the wallpaper gate (same explicit-fill recipe as the composer card) — so both frontends look identical to the reader.
 - 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.
 
@@ -144,7 +144,7 @@ deepseek-harness-background/          # the plugin repo (package name stays the
 │       ├── glass-registry.ts # third-party glass registry (window bridge + gated rule synthesis)
 │       ├── timeline/
 │       │   ├── index.tsx            # dock entry: mode dispatch + re-exports
-│       │   ├── official-enhance.tsx # dsh>=0.1.2: click interception + history warm-up
+│       │   ├── official-enhance.tsx # dsh>=0.1.2: smooth-jump interception (+ warm-up on the alpha.1/2 rail)
 │       │   ├── legacy-rail.tsx      # dsh<=0.1.1: ported official turn rail
 │       │   ├── legacy-rail-css.ts   # rail stylesheet (dsbt- prefixed, official metrics)
 │       │   ├── jump.ts              # shared jump engine (paging + glide + compensation)

package/README.zh.md

@@ -49,7 +49,7 @@
 - **主题自适应遮罩** —— 浅色主题用白色纱帘（把图片提亮保持深色文字对比度），深色主题自动换成黑色纱帘（压暗图片保持浅色文字对比度）。
 - **毛玻璃（白名单制）** —— 启用背景后，只有以小卡片/小按钮形态悬浮在壁纸上的表面才会变成半透明玻璃（顶部白色高光渐变 + `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 官网风格轮次导航轨：每一轮一个刻度，悬停或聚焦时预览该轮的问题。 两套前端、同一套后端，按当前内核支持的能力自动选择：   - **dsh ≥ 0.1.2（增强）** —— 内核已经自带这条导航轨，因此插件不渲染任何自己的界面，只修正它的行为： 点击由官方的瞬时跳转改为**平滑滑动**（缓入缓出、按距离定时长、读者一滚动立刻接管、`prefers-reduced-motion` 下直接定位）； 并且当读者把手伸向导航轨时自动往回翻页加载历史，让“需要点加载更多才出现”的轮次也长出刻度、可以直接跳转 —— 补到导航轨自身不压缩的刻度上限为止（再往后官方样式表会把刻度挤成无法瞄准的实心条）。官方悬浮预览卡是实心底，在壁纸门控下改为与输入卡同配方的毛玻璃（受「毛玻璃模糊」滑块驱动）；刻度列加上 DeepSeek 网页版式的上下渐隐（仅绘制层，不影响命中测试）。导航轨的高亮状态仍归内核自己维护——滑动走的是真实滚动容器，官方滚动处理会持续更新活动轮次与持久化滚动位置。   - **dsh ≤ 0.1.1（移植版）** —— 没有官方导航轨，插件渲染自己移植的同一套界面（完全相同的尺寸，同样带上玻璃 + 上下渐隐）， 数据来自同一套后端。 两种情况下，滑动前都会先解除宿主的底部跟随状态（流式增长、轮次结束重渲染都不会把视图拽回底部）；被 rewind 撤回的消息自动从轨道剔除； 历史翻页会补偿前置内容的高度，读者视野纹丝不动。用设置行里的时间线开关可关闭。
+- **会话时间线** —— 长会话右缘的 DeepSeek 官网风格轮次导航轨：每一轮一个刻度，悬停或聚焦时预览该轮的问题。 两套前端、同一套后端，按当前内核支持的能力自动选择：   - **dsh ≥ 0.1.2（增强）** —— 内核已经自带这条导航轨，因此插件不渲染任何自己的界面，只修正它仍欠缺的行为（按导航轨自己发布的度量做能力探测，绝不比较版本号）： 对**已加载**轮次的点击由官方的瞬时跳转改为**平滑滑动**（缓入缓出、按距离定时长、读者一滚动立刻接管、`prefers-reduced-motion` 下直接定位）。 在 **0.1.2-alpha.1/2** 上导航轨只列出已加载的轮次，因此读者把手伸向导航轨时还会自动往回翻页加载历史，让“需要点加载更多才出现”的轮次也长出刻度、可以直接跳转 —— 补到导航轨自身不压缩的刻度上限为止（再往后官方样式表会把刻度挤成无法瞄准的实心条）。 在 **0.1.2-alpha.3+** 上官方重构了导航轨（固定间距刻度在框内滚动，数据来自全会话轮次大纲：每一轮都在轨上，未加载的轮次由内核自行翻页），插件相应收窄为只保留平滑滑动 —— 点击索引按内核渲染的同一份合并阶梯解析，已加载窗口之外的刻度交给内核自己的跳转机器，历史预热不再运行。官方悬浮预览卡是实心底，在壁纸门控下改为与输入卡同配方的毛玻璃（受「毛玻璃模糊」滑块驱动）；刻度列加上 DeepSeek 网页版式的上下渐隐（仅绘制层，不影响命中测试）。导航轨的高亮状态仍归内核自己维护——滑动走的是真实滚动容器，官方滚动处理会持续更新活动轮次与持久化滚动位置。   - **dsh ≤ 0.1.1（移植版）** —— 没有官方导航轨，插件渲染自己移植的同一套界面（完全相同的尺寸，同样带上玻璃 + 上下渐隐）， 数据来自同一套后端。 两种情况下，滑动前都会先解除宿主的底部跟随状态（流式增长、轮次结束重渲染都不会把视图拽回底部）；被 rewind 撤回的消息自动从轨道剔除； 凡插件自己翻页加载历史的地方（移植轨与 alpha.1/2 轨），每一页都会补偿前置内容的高度，读者视野纹丝不动。用设置行里的时间线开关可关闭。
 - **持久化到官方设置文档** —— 存于 `$DSH_HOME/settings.yaml`，跨重启保留。
 - **干净卸载** —— 关闭、清除或卸载后完整恢复原背景；插件只移除自己写过的内容。
 
@@ -100,14 +100,14 @@ dsh --profile web
 | 毛玻璃模糊 | `0..40px` 半透明表面上的 `backdrop-filter` 模糊（1px 步进）。 |
 | 壁纸模糊 | `0..60px` 壁纸图片本身的模糊（2px 步进）。 |
 | 填充方式 | `cover`（铺满）或 `contain`（完整）。 |
-| 会话时间线 | 会话时间线的开关（默认开启）。dsh ≥ 0.1.2 上该项显示为**会话时间线增强**：官方导航轨保留，插件只优化其行为，关掉即恢复官方原样；旧内核上该项为**会话时间线**，开关控制插件自己移植的导航轨。 |
+| 会话时间线 | 会话时间线的开关（默认开启）。dsh ≥ 0.1.2 上该项显示为**会话时间线增强**：官方导航轨保留，插件只优化其行为，关掉即恢复官方原样（说明文案随内核代际分两版——alpha.1/2 完整增强，alpha.3+ 仅平滑跳转）；旧内核上该项为**会话时间线**，开关控制插件自己移植的导航轨。 |
 
 5. 点 **清除背景** 移除背景，恢复默认外观。
 
 ## 原理
 
 - **设置行**位于官方「通用」设置分区的 `settings.general.item` 槽中，紧挨「外观」行。控件样式全部使用 `--dsw-alias-*` 设计 token（按钮 / 胶囊 / 分段控件 / 滑块轨道与官方 chrome 一致），滑块为原生 `input[type=range]` 的 5% / 1–2px 步进 + 松手提交。
-- **会话时间线**注册进 `conversation.input.dock` 槽位（绑定每会话生命周期）。模式判定是对槽位 props 的能力探测，而不是比较版本号： 官方导航轨正是由 `ui-chat` 以会话 hook 形式发布的同一份索引渲染的（`useChat(s => s.navigation.items())`，dsh ≥ 0.1.2）， 所以这个 hook 存在**就是**官方导航轨存在 —— 而且它能扛住预发布版、fork 以及挂载了其它会话目标的部署。 hook 存在时插件什么都不渲染，只在**捕获阶段**拦截官方导航轨的点击（React 18 在冒泡阶段由根容器派发 `onClick`， 所以导航轨上的捕获监听先执行，`stopImmediatePropagation()` 让官方处理器根本收不到事件）；hook 不存在时插件渲染自己移植的导航轨，portal 到 `body`。 两者跑同一个跳转引擎。数据最快的来源是宿主侧会话投影（`bgTimeline`，注册于 `src/projection.ts`）， 它枚举整个会话的每一条用户消息（含会话视图尚未分页载人的轮次），已加载的 chat 节点窗口作为兜底； 该窗口以鸭子类型同时兼容两代内核，因为 0.1.2 把 Chat 快照从 `session.getSnapshot().chat` 迁到了 `useChat()` —— 这是本插件唯一一处破坏性变更。 历史预热只在读者把手伸向导航轨时运行，并停在导航轨不压缩的刻度上限（`floor((高度 - 12) / 10) + 1`）； 每一页都补偿前置内容的高度，因为宿主的 prepend 锚点在插件侧无法触及。移植版导航轨与增强后的官方轨采用完全一致的**玻璃 + 上下渐隐处理** —— 悬浮预览在壁纸门控下加入毛玻璃配方（与输入卡片同一显式填充配方），刻度列带 DeepSeek 网页版式上下渐隐，两个前端对读者的视觉完全一致。
+- **会话时间线**注册进 `conversation.input.dock` 槽位（绑定每会话生命周期）。模式判定是对槽位 props 的能力探测，而不是比较版本号： 官方导航轨正是由 `ui-chat` 以会话 hook 形式发布的同一份索引渲染的（`useChat(s => s.navigation.items())`，dsh ≥ 0.1.2）， 所以这个 hook 存在**就是**官方导航轨存在 —— 而且它能扛住预发布版、fork 以及挂载了其它会话目标的部署。 hook 存在时插件什么都不渲染，只在**捕获阶段**拦截官方导航轨的点击（React 18 在冒泡阶段由根容器派发 `onClick`， 所以导航轨上的捕获监听先执行，`stopImmediatePropagation()` 让官方处理器根本收不到事件）——点击索引按内核实际渲染的阶梯解析：压缩式 alpha.1/2 轨上是已加载条目本身，alpha.3 帧式轨上则是与内核同构的「大纲 + 已加载」合并阶梯，已加载窗口之外（无锚键）的刻度交给内核自己的穿越加载跳转——且当内核跳转仍在翻页（标记以 `aria-busy` 脉冲）时插件整体让位：内核的已加载分支落点前会先取消自己的在途跳转，拦截会绕过这一取消；hook 不存在时插件渲染自己移植的导航轨，portal 到 `body`。 两者跑同一个跳转引擎。数据最快的来源是宿主侧会话投影（`bgTimeline`，注册于 `src/projection.ts`）， 它枚举整个会话的每一条用户消息（含会话视图尚未分页载人的轮次），已加载的 chat 节点窗口作为兜底； 该窗口以鸭子类型同时兼容两代内核，因为 0.1.2 把 Chat 快照从 `session.getSnapshot().chat` 迁到了 `useChat()` —— 这是本插件唯一一处破坏性变更。 历史预热只在读者把手伸向导航轨时运行——而且只在其仍有意义的地方运行：压缩式 alpha.1/2 轨与移植轨，并停在导航轨不压缩的刻度上限（`floor((高度 - 12) / 10) + 1`）； alpha.3 帧式轨已列出每一轮并自行按需翻页，预热只会与内核的翻页器相互踩踏，故不运行。 每一页都补偿前置内容的高度，因为宿主的 prepend 锚点在插件侧无法触及。移植版导航轨与增强后的官方轨采用完全一致的**玻璃 + 上下渐隐处理** —— 悬浮预览在壁纸门控下加入毛玻璃配方（与输入卡片同一显式填充配方），刻度列带 DeepSeek 网页版式上下渐隐，两个前端对读者的视觉完全一致。
 - 插件自有的 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` 锁定。
@@ -141,7 +141,7 @@ deepseek-harness-background/          # 插件仓库（包名保留 npm 风格 i
 │       ├── glass-registry.ts # 第三方毛玻璃注册表（window 桥 + 门控规则合成）
 │       ├── timeline/
 │       │   ├── index.tsx            # 停靠入口：模式分发与再导出
-│       │   ├── official-enhance.tsx # dsh>=0.1.2：点击拦截 + 历史预热
+│       │   ├── official-enhance.tsx # dsh>=0.1.2：平滑跳转拦截（+ alpha.1/2 轨历史预热）
 │       │   ├── legacy-rail.tsx      # dsh<=0.1.1：移植的官方轮次导航轨
 │       │   ├── legacy-rail-css.ts   # 导航轨样式（dsbt- 前缀，官方尺寸）
 │       │   ├── jump.ts              # 共享跳转引擎（翻页 + 滑动 + 补偿）

package/lib/client.js

@@ -969,6 +969,7 @@ window.__ModuleLoader__.load({
 			"background.timelineHint": "右侧轮次导航轨，悬停预览该轮问题与直达更早历史",
 			"background.timelineEnhance": "会话时间线增强",
 			"background.timelineEnhanceHint": "为官方会话时间线补上平滑跳转，并可直达需要“加载更多”的更早轮次",
+			"background.timelineEnhanceNarrowHint": "为官方会话时间线的已加载轮次补上平滑跳转",
 			"timeline.railLabel": "轮次导航",
 			"timeline.noText": "（无文本内容）",
 			"timeline.jump": "跳转到第 {turn} 轮"
@@ -1003,6 +1004,7 @@ window.__ModuleLoader__.load({
 			"background.timelineHint": "Turn rail at the right edge; hover to preview a turn and reach earlier history",
 			"background.timelineEnhance": "Conversation timeline enhancement",
 			"background.timelineEnhanceHint": "Adds smooth jumps and direct reach into turns that still need “load earlier”",
+			"background.timelineEnhanceNarrowHint": "Adds smooth jumps for the rail's loaded turns",
 			"timeline.railLabel": "Turn navigation",
 			"timeline.noText": "(no text)",
 			"timeline.jump": "Jump to turn {turn}"
@@ -1165,41 +1167,41 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var SettingsRow_module_css_default = {
-			"sliderValue": "-ozqdq_sliderValue",
-			"btnPrimary": "-ozqdq_btnPrimary",
+			"header": "-ozqdq_header",
+			"urlRow": "-ozqdq_urlRow",
+			"previewImg": "-ozqdq_previewImg",
+			"segGroup": "-ozqdq_segGroup",
+			"switchKnob": "-ozqdq_switchKnob",
+			"hint": "-ozqdq_hint",
+			"slider": "-ozqdq_slider",
+			"segLabel": "-ozqdq_segLabel",
+			"segActive": "-ozqdq_segActive",
 			"desc": "-ozqdq_desc",
-			"previewScrim": "-ozqdq_previewScrim",
-			"section": "-ozqdq_section",
+			"switch": "-ozqdq_switch",
 			"sliderLabel": "-ozqdq_sliderLabel",
-			"title": "-ozqdq_title",
-			"previewGlass": "-ozqdq_previewGlass",
-			"urlInput": "-ozqdq_urlInput",
-			"segGroup": "-ozqdq_segGroup",
+			"previewScrim": "-ozqdq_previewScrim",
 			"segRow": "-ozqdq_segRow",
-			"btn": "-ozqdq_btn",
-			"clearRow": "-ozqdq_clearRow",
-			"previewImg": "-ozqdq_previewImg",
-			"slider": "-ozqdq_slider",
-			"btnDanger": "-ozqdq_btnDanger",
-			"sourceRow": "-ozqdq_sourceRow",
-			"previewEmpty": "-ozqdq_previewEmpty",
+			"titleRow": "-ozqdq_titleRow",
 			"error": "-ozqdq_error",
-			"switch": "-ozqdq_switch",
-			"sliderRow": "-ozqdq_sliderRow",
-			"segLabel": "-ozqdq_segLabel",
-			"sectionLabel": "-ozqdq_sectionLabel",
-			"header": "-ozqdq_header",
-			"clearBtn": "-ozqdq_clearBtn",
 			"preview": "-ozqdq_preview",
+			"btnDanger": "-ozqdq_btnDanger",
+			"section": "-ozqdq_section",
 			"previewGlassText": "-ozqdq_previewGlassText",
-			"enabledBadge": "-ozqdq_enabledBadge",
+			"previewGlass": "-ozqdq_previewGlass",
+			"sliderValue": "-ozqdq_sliderValue",
+			"sourceRow": "-ozqdq_sourceRow",
+			"btn": "-ozqdq_btn",
+			"sliderRow": "-ozqdq_sliderRow",
 			"segBtn": "-ozqdq_segBtn",
-			"segActive": "-ozqdq_segActive",
-			"titleRow": "-ozqdq_titleRow",
-			"switchKnob": "-ozqdq_switchKnob",
 			"row": "-ozqdq_row",
-			"urlRow": "-ozqdq_urlRow",
-			"hint": "-ozqdq_hint"
+			"title": "-ozqdq_title",
+			"enabledBadge": "-ozqdq_enabledBadge",
+			"sectionLabel": "-ozqdq_sectionLabel",
+			"btnPrimary": "-ozqdq_btnPrimary",
+			"clearRow": "-ozqdq_clearRow",
+			"urlInput": "-ozqdq_urlInput",
+			"clearBtn": "-ozqdq_clearBtn",
+			"previewEmpty": "-ozqdq_previewEmpty"
 		};
 		//#endregion
 		//#region src/client/SettingsRow.tsx
@@ -1366,8 +1368,8 @@ window.__ModuleLoader__.load({
 		function BackgroundSettingsRow({ t }) {
 			const snapshot = (0, react.useSyncExternalStore)(settingsClient.subscribe, readSnapshot);
 			const navMode = (0, react.useSyncExternalStore)(subscribeTimelineMode, timelineMode);
-			const timelineLabelKey = navMode === "enhance" ? "background.timelineEnhance" : "background.timeline";
-			const timelineHintKey = navMode === "enhance" ? "background.timelineEnhanceHint" : "background.timelineHint";
+			const timelineLabelKey = navMode === "legacy" ? "background.timeline" : "background.timelineEnhance";
+			const timelineHintKey = navMode === "narrow" ? "background.timelineEnhanceNarrowHint" : navMode === "enhance" ? "background.timelineEnhanceHint" : "background.timelineHint";
 			const [draft, setDraft] = (0, react.useState)(DEFAULTS);
 			const [uploading, setUploading] = (0, react.useState)(false);
 			const [urlText, setUrlText] = (0, react.useState)("");
@@ -2032,7 +2034,8 @@ window.__ModuleLoader__.load({
 			for (;;) {
 				if (rowRenderedInDom(anchorKey)) break;
 				const snapshot = session.getSnapshot();
-				if ((snapshot?.chat?.nodes?.get(anchorKey) ?? snapshot?.nodes?.get(anchorKey)) !== void 0) break;
+				const keyedNodeOf = (store) => store !== null && typeof store === "object" && typeof store.get === "function" ? store.get(anchorKey) : void 0;
+				if ((keyedNodeOf(snapshot?.chat?.nodes) ?? keyedNodeOf(snapshot?.nodes)) !== void 0) break;
 				if (snapshot?.hasMore !== true) break;
 				if (Date.now() >= deadline) break;
 				if (snapshot.loadingOlder === true) {
@@ -2133,9 +2136,11 @@ window.__ModuleLoader__.load({
 			return Math.max(2, Math.floor(usable / 10) + 1);
 		}
 		/**
-		* Resolve the entry under a pointer Y — the official geometry verbatim
-		* (`itemAtPointer` in TurnNavigator.tsx), so this plugin lands on exactly the
-		* mark the official rail would have picked.
+		* Resolve the entry under a pointer Y on the COMPRESSING rail — the official
+		* alpha.1/2 geometry verbatim (`itemAtPointer` in that generation's
+		* TurnNavigator.tsx), so this plugin lands on exactly the mark the official
+		* rail would have picked. The legacy port (whose own rail never scrolls
+		* internally) uses the same mapping, where ratio and fixed pitch coincide.
 		* @param count - number of entries the rail shows.
 		* @param rail - the rail element.
 		* @param clientY - pointer viewport Y.
@@ -2148,11 +2153,45 @@ window.__ModuleLoader__.load({
 			return Math.round(ratio * (count - 1));
 		}
 		/**
+		* Whether `rail` is the frame-style rail (dsh >= 0.1.2-alpha.3): marks sit
+		* at a fixed pitch and scroll INSIDE the frame, whose scroller offset the
+		* component publishes inline as `--turn-scroll-top` — every render, resting
+		* at `0px` included. The compressing alpha.1/2 rail never publishes that
+		* property, so its presence is the generation test. The legacy port paints
+		* its own `--dsbt-*` properties and can never trip this.
+		* @param rail - the rail element (or null).
+		*/
+		function isFrameRail(rail) {
+			return rail !== null && rail.style.getPropertyValue("--turn-scroll-top") !== "";
+		}
+		/**
+		* Resolve the entry under a pointer Y on the frame-style rail — the official
+		* alpha.3 geometry verbatim (`itemAtPointer` in that generation's
+		* TurnNavigator.tsx): marks live in the scrolled ladder at a fixed 10px
+		* pitch, so the click offset adds the scroller offset. Read off the published
+		* `--turn-scroll-top` var rather than the scroller element itself — the same
+		* metric the official preview positioning uses, so any one-frame render lag
+		* affects both identically.
+		* @param count - number of entries the rail shows.
+		* @param rail - the rail element.
+		* @param clientY - pointer viewport Y.
+		*/
+		function frameIndexAtPointer(count, rail, clientY) {
+			const rect = rail.getBoundingClientRect();
+			const inset = railInsetOf(rail);
+			const raw = Number.parseFloat(rail.style.getPropertyValue("--turn-scroll-top"));
+			const scrollTop = Number.isFinite(raw) ? raw : 0;
+			const offset = clientY - rect.top + scrollTop - inset;
+			return Math.max(0, Math.min(count - 1, Math.round(offset / 10)));
+		}
+		/**
 		* Resolve the gesture that produced a rail click to an entry index.
 		*
 		* Keyboard activation targets the focused mark button (recovered by its
 		* position among the rail's buttons); a mouse click carries coordinates and
-		* resolves through the rail geometry. Returns -1 when neither applies.
+		* resolves through the rail geometry — the frame-style alpha.3 mapping when
+		* the rail publishes `--turn-scroll-top`, the compressing alpha.1/2 mapping
+		* otherwise. Returns -1 when neither applies.
 		*
 		* Assumption (both frontends): the mark ticks are the ONLY buttons under the
 		* rail — the official rail renders marks exclusively and its preview tooltip
@@ -2172,7 +2211,8 @@ window.__ModuleLoader__.load({
 				}
 			}
 			const count = rail.querySelectorAll("button").length;
-			return count === 0 ? -1 : indexAtPointer(count, rail, event.clientY);
+			if (count === 0) return -1;
+			return isFrameRail(rail) ? frameIndexAtPointer(count, rail, event.clientY) : indexAtPointer(count, rail, event.clientY);
 		}
 		/**
 		* Validate the official navigation array crossing the slot boundary. The
@@ -2200,6 +2240,63 @@ window.__ModuleLoader__.load({
 			}
 			return out;
 		}
+		/**
+		* Validate one `turnOutline` wire value into its entries. The value is the
+		* host projection's wire view (an array of `{ turn, seq, prompt, response }`
+		* — see `dsh-session-turn-outline`) read through `useProjection`, so it may
+		* be absent (pre-baseline, or an older kernel that never registers the key —
+		* which reads `undefined`), partial, or damaged. `turn` and `seq` are the
+		* load-bearing fields — a mark cannot exist or page without them — and a
+		* damaged one drops the entry; the previews are decorative and degrade to ''.
+		* @param value - the raw `useProjection('turnOutline')` value.
+		*/
+		function normalizeOutlineItems(value) {
+			if (!Array.isArray(value)) return [];
+			const out = [];
+			for (const item of value) {
+				if (item === null || typeof item !== "object") continue;
+				const rec = item;
+				if (typeof rec.turn !== "number" || !Number.isSafeInteger(rec.turn) || rec.turn < 0) continue;
+				if (typeof rec.seq !== "number" || !Number.isSafeInteger(rec.seq) || rec.seq < 0) continue;
+				out.push({
+					turn: rec.turn,
+					seq: rec.seq,
+					prompt: typeof rec.prompt === "string" ? rec.prompt : "",
+					response: typeof rec.response === "string" ? rec.response : ""
+				});
+			}
+			return out;
+		}
+		/**
+		* Rebuild the rail's full mark ladder exactly as the official ChatView does
+		* (a mirror of `mergeTurnRailItems` in dsh-client-ui-chat): outline entries
+		* seed every known turn as unloaded, loaded items then override with their
+		* anchor key and richer previews, ascending by turn. The enhancer maps a
+		* click to a mark by INDEX, so its ladder must match the RENDERED marks —
+		* which are exactly this merge on an alpha.3 kernel; without the outline
+		* value the merge degrades to the loaded items (the alpha.1/2 ladder).
+		* @param loaded - the validated loaded-window items.
+		* @param outline - the raw turnOutline wire value.
+		*/
+		function mergeRailItems(loaded, outline) {
+			const byTurn = /* @__PURE__ */ new Map();
+			for (const entry of normalizeOutlineItems(outline)) byTurn.set(entry.turn, {
+				turn: entry.turn,
+				prompt: entry.prompt,
+				response: entry.response
+			});
+			for (const item of loaded) {
+				const preview = byTurn.get(item.turn);
+				byTurn.set(item.turn, {
+					turn: item.turn,
+					prompt: item.prompt !== "" ? item.prompt : preview?.prompt ?? "",
+					response: item.response !== "" ? item.response : preview?.response ?? "",
+					anchorKey: item.anchorKey
+				});
+			}
+			if (byTurn.size === 0) return [];
+			return [...byTurn.values()].sort((left, right) => left.turn - right.turn);
+		}
 		//#endregion
 		//#region src/client/timeline/source.ts
 		/**
@@ -2935,18 +3032,31 @@ window.__ModuleLoader__.load({
 		* turn navigator (dsh >= 0.1.2, `TurnNavigator` in dsh-client-ui-chat).
 		*
 		* This component renders NOTHING. It borrows the official rail exactly as the
-		* kernel painted it and fixes two behaviours:
+		* kernel painted it and fixes its behaviours, scoped to what the running rail
+		* generation still lacks (told apart by capability — see isFrameRail — never
+		* by version compare):
 		*
-		* 1. Smooth jump. The official `navigateToTurn` is one assignment
-		*    (`el.scrollTop += flowTop(row, el) - 24`); a click across a long
-		*    transcript teleports. Clicks are intercepted in the CAPTURE phase and
-		*    re-run through the shared glide instead.
-		* 2. Reachable history. The official rail only lists turns the client has
-		*    already loaded, so anything behind the "load earlier" button has no mark
-		*    at all. Hovering or focusing the rail pages older history in — only up
-		*    to the rail's own uncompressed capacity, so the marks never degrade into
-		*    a solid bar — with the scroll position compensated so the reader's view
-		*    never moves.
+		* 1. Smooth jump (every generation). The official `navigateToTurn` is one
+		*    assignment (`el.scrollTop += flowTop(row, el) - 24`); a click across a
+		*    long transcript teleports. Clicks on LOADED marks are intercepted in the
+		*    capture phase and re-run through the shared glide instead. Since
+		*    0.1.2-alpha.3 the rail also renders marks for turns OUTSIDE the loaded
+		*    window (fed by the whole-log `turnOutline` projection); those jumps
+		*    page history through the kernel's own loadThrough machinery — marks
+		*    without an anchor key are left to it, and the click index is resolved
+		*    against the same merged ladder the kernel renders. While one of those
+		*    kernel jumps is still paging (a mark pulses `aria-busy`), the plugin
+		*    stands down entirely: the kernel's loaded branch cancels its own pending
+		*    jump before landing, and an interception would bypass that cancellation.
+		* 2. Reachable history (compressing rail only — dsh 0.1.2-alpha.1/2). That
+		*    rail only lists turns the client has already loaded, so anything behind
+		*    the "load earlier" button has no mark at all. Hovering or focusing the
+		*    rail pages older history in — only up to the rail's own uncompressed
+		*    capacity, so the marks never degrade into a solid bar — with the scroll
+		*    position compensated so the reader's view never moves. The alpha.3
+		*    frame-style rail lists every turn already and pages on demand itself, so
+		*    warming there would fight the kernel's pager for nothing and does not
+		*    run.
 		*
 		* State-ownership note (why intercepting the official click loses nothing):
 		* the kernel's scrollport (`data-conversation-scroll`, ChatView's
@@ -2972,7 +3082,12 @@ window.__ModuleLoader__.load({
 		* Nothing here touches the official DOM: no nodes are injected into a
 		* React-owned subtree and no official class or paint is overridden.
 		*/
-		/** Structural anchor of the official rail (its inline style carries the rail's own metrics). */
+		/**
+		* Structural anchor of the official rail — its inline style carries the rail's
+		* own metrics, which BOTH generations publish (`--turn-natural-height`), so
+		* one selector finds either and the generation itself is told apart by
+		* isFrameRail afterwards.
+		*/
 		const OFFICIAL_RAIL_SELECTOR = "[data-conversation-scroll] nav[style*=\"--turn-natural-height\"]";
 		/**
 		* Rails claimed by an enhancer instance, keyed by the owning instance's
@@ -2988,20 +3103,26 @@ window.__ModuleLoader__.load({
 		/** How often the official rail is looked for (it mounts with the chat view). */
 		const RAIL_POLL_MS = 400;
 		/**
-		* The enhancer: no visual output, only the two behaviour fixes.
+		* The enhancer: no visual output, only the behaviour fixes the running rail
+		* generation lacks.
 		* @param props - dock slot props plus the enabled gate.
 		* @returns null (always).
 		*/
 		function OfficialTimelineEnhancer(props) {
-			const { sessionId, sessionsService, useChat, enabled } = props;
+			const { sessionId, sessionsService, useChat, useProjection, enabled } = props;
 			const items = normalizeNavigationItems(useChat === void 0 ? void 0 : useChat((snapshot) => {
 				const nav = snapshot?.navigation;
 				return typeof nav?.items === "function" ? nav.items() : void 0;
 			}));
+			const ladder = mergeRailItems(items, useProjection === void 0 ? void 0 : useProjection("turnOutline"));
 			const session = sessionId !== void 0 && sessionsService !== void 0 ? sessionsService.binding(sessionId)?.session : void 0;
 			const [rail, setRail] = react.default.useState(null);
+			/** Frame-style rail (dsh >= 0.1.2-alpha.3): decides the warm-up's presence. */
+			const [narrow, setNarrow] = react.default.useState(false);
 			const itemsRef = react.default.useRef(items);
 			itemsRef.current = items;
+			const ladderRef = react.default.useRef(ladder);
+			ladderRef.current = ladder;
 			const railRef = react.default.useRef(rail);
 			railRef.current = rail;
 			const aliveRef = react.default.useRef(true);
@@ -3029,6 +3150,8 @@ window.__ModuleLoader__.load({
 					}
 					claimedRails.set(found, claimToken);
 					setRail(found);
+					setNarrow(isFrameRail(found));
+					reportTimelineMode(isFrameRail(found) ? "narrow" : "enhance");
 				};
 				check();
 				const timer = window.setInterval(check, RAIL_POLL_MS);
@@ -3038,6 +3161,7 @@ window.__ModuleLoader__.load({
 				};
 			}, [claimToken]);
 			const navigate = react.default.useCallback((item) => {
+				if (item.anchorKey === void 0) return;
 				if (sessionsService === void 0 || sessionId === void 0) return;
 				const scrollport = rail === null ? null : rail.closest("[data-conversation-scroll]");
 				jumpToMessage(sessionsService, sessionId, item.anchorKey, {
@@ -3075,9 +3199,10 @@ window.__ModuleLoader__.load({
 			react.default.useEffect(() => {
 				if (!enabled || rail === null) return;
 				const onClick = (event) => {
+					if (rail.querySelector("[aria-busy=\"true\"]") !== null) return;
 					const index = indexForEvent(rail, event);
-					const item = itemsRef.current[index];
-					if (item === void 0) return;
+					const item = ladderRef.current[index];
+					if (item === void 0 || item.anchorKey === void 0) return;
 					event.preventDefault();
 					event.stopImmediatePropagation();
 					navigate(item);
@@ -3092,7 +3217,7 @@ window.__ModuleLoader__.load({
 				navigate
 			]);
 			react.default.useEffect(() => {
-				if (!enabled || rail === null) return;
+				if (!enabled || narrow || rail === null) return;
 				const start = () => {
 					warm();
 				};
@@ -3104,6 +3229,7 @@ window.__ModuleLoader__.load({
 				};
 			}, [
 				enabled,
+				narrow,
 				rail,
 				warm
 			]);