dsh-turn-navigator 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.4.2] - 2026-09-05
+
+### Docs
+
+- **README relaunch with dsh-versioned differentiation (bilingual)**. The official-rail comparison table now names its targets explicitly — **dsh 0.1.3-alpha.1** official `TurnNavigator` vs **DSH STN v0.4.2** — reflecting that as of 0.1.3 the built-in rail added full-session scope (host `turnOutline` projection) and out-of-window load-and-jump, and marking what still separates DSH STN (switchable/disableable rail, timestamped full-summary tooltip, scroll buttons + wave hover, external read-only plugin, zero host changes) plus what applies on dsh ≤ 0.1.2 (where the official rail is still loaded-window only). A new bilingual **Version map** section maps each DSH STN release to its dsh baseline (≤ 0.1.1 legacy RPC / 0.1.2+ journal channel / 0.1.3-alpha.1 structural review).
+
 ## [0.4.1] - 2026-09-03
 
 ### Fixed

package/README.md

@@ -10,7 +10,7 @@ DSH Smoothly Turn Nav (**DSH STN**) is an external plugin for [DeepSeek Harness]
 
 ## Why
 
-In the default DSH web UI, the official turn rail only shows the **currently loaded window** of turns — in a long conversation, most turns are invisible until you scroll and load more. DSH STN solves this:
+In the default DSH web UI, the official turn rail historically showed only the **currently loaded window** of turns — in a long conversation, most turns are invisible until you scroll and load more. As of dsh **0.1.3-alpha.1** the built-in rail also gained full-session scope and out-of-window jumps through a host-side `turnOutline` projection, but it still **cannot be switched off**. DSH STN solves the long-session problem and stays fully replaceable:
 
 - **Full history at a glance** — every persisted turn is shown as plain data, including turns far outside the loaded window. No scrolling, no loading, no waiting.
 - **Hover to preview** — the capsule glows with the theme color and widens in a wave ripple; a DSH-style tooltip shows the turn's number, time, and user-message summary.
@@ -24,32 +24,47 @@ In the default DSH web UI, the official turn rail only shows the **currently loa
 | 🗺️ **Full-history minimap** | All turns visible immediately — read from the persisted session log as data, **zero prepends** into the conversation flow on open (long sessions stay responsive) |
 | 🎹 **Piano-key design** | One capsule per turn, ~3px tall, right-aligned on the right edge; auto-sizing (up to 30vh) with an internal hidden scrollbar |
 | 🌊 **Wave hover** | Hovered capsule glows with the theme color and widens 150% leftward; its two neighbours widen 125% — a ripple across the rail |
-| 💬 **Rich tooltip** | Turn number, timestamp, and full user-message summary, always fully inside the viewport |
+| 💬 **Rich tooltip** | Turn **number, timestamp, and full user-message summary**, always fully inside the viewport |
 | 🎯 **Jump to any turn** | Precise `scrollTop` targeting (no `scrollIntoView` fights); out-of-window jumps extend the window on demand with a "Locating turn N…" pulse + bubble; the oldest-turn jump loads to the **true first turn** (`hasMore = false`) |
-| 👁️ **Follow-scroll highlight** | The capsule of the turn at the reading line is tinted as you scroll |
+| 👁️ **Follow-scroll highlight** | The capsule of the turn at the reading line is tinted as you scroll — and the rail's own viewport keeps the active turn in view |
 | ⬆️⬇️ **Scroll buttons** | Click or hover-hold to scroll the rail; greyed out when there is nothing to scroll |
-| 🎛️ **Rail mode switch** | Settings → General → *Turn navigation*: `DSH official` / `DSH STN` (default) / `Hide all` — persisted across reloads |
+| 🎛️ **Rail mode switch** | Settings → General → *Turn navigation*: `DSH official` / `DSH STN` (default) / `Hide all` — persisted across reloads, so the official rail can finally be **turned off** |
 | 🔌 **Pure external plugin** | No DSH source code modified; no host changes; no new dependencies; read-only DOM access |
 
 ## vs. the official DSH turn rail
 
-The official built-in `TurnNavigator` has **no off-switch** and is always rendered in the chat view. DSH STN is the upgrade:
+The official built-in `TurnNavigator` has **no off-switch** and is always rendered in the chat view. The table below compares it at **dsh 0.1.3-alpha.1** (the current DSH web `TurnNavigator`, which re-added full-session scope via its own host projection) against this plugin, **DSH STN v0.4.2**:
 
-| Capability | DSH official rail | DSH STN |
+| Capability | DSH official rail (0.1.3-alpha.1) | DSH STN (v0.4.2) |
 |---|---|---|
-| Turns shown | Only the **loaded window** | **Every persisted turn** (full history) |
-| Jump to a turn outside the window | ❌ Not visible, not reachable | ✅ On-demand window extension + feedback |
-| Long-session open performance | Window rendering | **Zero prepend** — no flow re-render, no stall |
-| Follow-scroll highlight | ✅ | ✅ |
-| Hover preview | Prompt + response (≤160 chars each) | Number + time + full summary tooltip |
-| Wave ripple animation | ❌ | ✅ |
-| Scroll buttons (click / hover-hold) | ❌ | ✅ |
-| Rail height | Fixed band, compressed proportionally (≤420px) | Auto-sized (≤30vh), internal scroll |
+| Turns shown | **Every turn** — host `turnOutline` projection (0.1.3+) | Every persisted turn — **client-side** journal read |
+| How full history is read | Host-side projection embedded in the snapshot | Client pages the persisted journal (`session/page`); older dsh falls back to `sessions.history` RPC — **zero host changes** |
+| Jump to a turn outside the window | ✅ (0.1.3+ unloaded anchor pages history by seq) | ✅ on-demand window extension + "Locating turn N…" pulse/bubble |
+| Long-session open performance | Reads the projection | **Zero prepend** — plain data, no flow re-render, no stall |
+| Follow-scroll highlight | ✅ (0.1.3+ keeps the active mark in the rail viewport, with a pointer guard) | ✅ (v0.4.1+, same pointer-guarded follow) |
+| Hover preview | Prompt + response (≤3 lines each), no timestamp | Turn number + **timestamp** + full user-message summary |
+| Wave ripple animation | ❌ (fixed-pitch ticks widen instead) | ✅ wave ripple |
+| Scroll buttons (click / hover-hold) | ❌ (wheel + gradient fade) | ✅ click / hover-hold |
+| Rail height | Dynamic band (natural height … 420px) | Auto-sized (≤30vh), internal hidden scrollbar |
 | Narrow viewport (<900px) | Auto-hidden | Auto-hidden (mirrors official) |
-| Hide / switch rail | ❌ No off-switch | ✅ Settings → General → 3 modes |
-| Keyboard reachable | ✅ (focus ring) | ✅ (buttons) |
+| **Hide / switch rail** | ❌ no off-switch | ✅ Settings → General → 3 modes; `Hide all` hides both |
+| Keyboard accessibility | ✅ focus ring + `aria-current`/`aria-busy`/`aria-describedby` | ✅ focusable buttons (`Turn N — time — summary` aria-label) |
 | Source | Built-in, cannot be disabled | External plugin, **can be replaced/disabled** |
 
+As of dsh 0.1.3 the built-in rail caught up on full-session scope and out-of-window jumps. What still sets DSH STN apart: you can **switch it off** (the official rail cannot), the tooltip carries the **timestamp + full summary**, there are **scroll buttons and wave hover**, and it remains an **external, read-only plugin with zero host changes**. And on dsh ≤ 0.1.2 the built-in rail is simpler still (loaded window only), so the gap DSH STN closes is even larger there.
+
+## Version map
+
+Which DSH STN release matches which dsh:
+
+| DSH STN | dsh | Notes |
+|---|---|---|
+| v0.1.x | dsh ≤ 0.1.1 | Full history via the legacy `sessions.history` browser→host RPC |
+| v0.2.x – v0.4.1 | dsh 0.1.2+ | Adapted to the `ui-chat` refactor; full history via the journal `session/page` channel; v0.4.1 fixed true turn numbers and rail-viewport follow |
+| **v0.4.2** | dsh 0.1.2+, incl. **0.1.3-alpha.1** | This release: comparison/positioning updated against the 0.1.3 official rail (see above) |
+
+The official-rail comparison in this README targets **dsh 0.1.3-alpha.1**; on older dsh the official rail is simpler, so DSH STN's advantage is larger there.
+
 ## Installation
 
 ```sh
@@ -67,7 +82,7 @@ dsh web
 0. **Choose which rail to show** (Settings → General → **Turn navigation**): `DSH official` (the built-in rail), `DSH STN` (this plugin's rail — **default**), or `Hide all`. The official rail has no off-switch, so choosing DSH STN hides it with a stylesheet override and our rail takes over the right-edge center position. The choice persists across reloads.
 1. Open any conversation with at least one completed turn.
 2. A vertical rail of grey capsules appears on the right edge (one per turn). It **auto-sizes** — short conversations get a short rail, long ones hit the 30vh cap and scroll internally (hidden scrollbar, no layout jitter).
-3. **Hover** a capsule: it glows, widens in a wave, and shows the turn's index, timestamp, and summary in a tooltip to the left of the rail.
+3. **Hover** a capsule: it glows, widens in a wave, and shows the turn's **number, timestamp, and summary** in a tooltip to the left of the rail.
 4. **Click** a capsule to jump to that turn's start. Out-of-window turns pulse the capsule and show a "Locating turn N…" bubble while the window is extended on demand; the target row is highlighted on arrival. The activated capsule centers in the rail (unless it is the first or last turn).
 5. **Scroll** with the mouse wheel, the up/down buttons, or hover-hold on the buttons.
 
@@ -83,12 +98,12 @@ The plugin registers **two additive slots** — **no DSH source code is modified
 - **Full history as data**: on dsh 0.1.2+ the rail pages the same persisted log the official window reads, through the Typert Remote `session/page` channel (`ctx.remote.session` — mounted by the base web assembly; **no host changes, no new dependencies**). On older dsh it uses the `sessions.history` RPC. Every turn is derived from raw `turn/start` / `user/message` / `turn/end` events as plain data.
 - **On-demand jumps**: clicking a turn already in the window scrolls directly; for a turn outside it, the rail extends the window page by page through the official session store (`loadOlder`, with the authoritative `hasMore` as the loop terminator) until the target is in view — the only path that touches the flow, and it runs only when you click.
 - **Precise scrolling**: the rail locates the turn's first chat-node key, finds its DOM row via `data-chat-anchor-key`, and sets the scrollport's `scrollTop` directly (more predictable than `scrollIntoView`).
-- **Replacing the official rail**: the official rail lives inside the conversation scroll container; a container-scoped stylesheet rule (driven by the mode switch) hides it, and the rail takes over its right-edge center position. If a future dsh changes that structure, the worst case is the official rail reappearing (side by side) — never a crash.
+- **Replacing the official rail**: the official rail lives inside the conversation scroll container; a container-scoped stylesheet rule (driven by the mode switch) hides it, and the rail takes over its right-edge center position. Verified structurally against dsh 0.1.3-alpha.1 — the `[data-conversation-scroll] nav` hide rule still matches. If a future dsh changes that structure, the worst case is the official rail reappearing (side by side) — never a crash.
 - **Read-only**: the plugin never writes to DSH state, never sends data anywhere, and only reads the DOM for targeting.
 
 ## Compatibility
 
-- DeepSeek Harness (dsh) with the web client (`dsh web`).
+- DeepSeek Harness (dsh) with the web client (`dsh web`); developed and verified against dsh 0.1.2+ and reviewed against dsh 0.1.3-alpha.1.
 - Requires the `conversation.session.header.utilities` and `settings.general.item` slot declarations (present in current DSH).
 - Default `DSH STN` mode hides the official rail (stylesheet override) and centers our rail in its place; `DSH official` mode shows the built-in rail instead; `Hide all` hides both. Both rails auto-hide below 900px width.
 - Coexists with full-screen plugin pages (e.g. the kanban board): the rail sits below their overlay layer.
@@ -102,4 +117,4 @@ The plugin registers **two additive slots** — **no DSH source code is modified
 
 ## License
 
-MIT
+MIT

package/README.zh.md

@@ -10,7 +10,7 @@ DSH Smoothly Turn Nav（**DSH STN**）是 [DeepSeek Harness](https://github.com/
 
 ## 为什么需要
 
-DSH Web UI 的官方轮次胶囊条只显示**当前已加载窗口内**的轮次——长会话里，大部分轮次要滚动加载后才可见。DSH STN 解决这个问题：
+默认 DSH Web UI 的官方轮次胶囊条**历史上**只显示**当前已加载窗口内**的轮次——长会话里，大部分轮次要滚动加载后才可见。从 dsh **0.1.3-alpha.1** 起，官方胶囊条也通过宿主侧 `turnOutline` 投影补上了紧要的全会话范围与窗口外跳转，但它依然**无法关闭**。DSH STN 解决长会话问题，并且始终可替换：
 
 - **全量历史一眼可见**——所有持久化轮次以纯数据呈现，包括远在已加载窗口之外的轮次。不滚动、不加载、不等待。
 - **悬停即预览**——胶囊以主题色亮起并泛起波浪涟漪；DSH 风格 Tooltip 展示该轮序号、时间与用户消息摘要。
@@ -24,32 +24,47 @@ DSH Web UI 的官方轮次胶囊条只显示**当前已加载窗口内**的轮
 | 🗺️ **全量历史迷你地图** | 所有轮次立即可见——从持久化会话日志以数据读取，**打开会话零 prepend**（长会话保持流畅） |
 | 🎹 **钢琴键设计** | 每轮一个约 3px 高的胶囊，右缘右对齐；长度自适应（上限 30vh），超出后内部滚动（滚动条隐藏） |
 | 🌊 **波浪悬停** | 悬停的胶囊以主题色亮起并向左加宽 150%，相邻两个加宽 125%——滑过时如波浪起伏 |
-| 💬 **丰富 Tooltip** | 轮次序号、时间戳、完整用户消息摘要，始终完整显示在视口内 |
+| 💬 **丰富 Tooltip** | 轮次**序号、时间戳、完整用户消息摘要**，始终完整显示在视口内 |
 | 🎯 **跳转任意轮** | 精确 `scrollTop` 定位（不与 `scrollIntoView` 打架）；窗口外跳转按需扩展窗口并显示"正在定位第 N 轮…"脉冲+气泡；最老轮次跳转加载到**真正第一轮**（`hasMore = false`） |
-| 👁️ **滚动跟随高亮** | 阅读线所在轮次的胶囊随滚动点亮 |
+| 👁️ **滚动跟随高亮** | 阅读线所在轮次的胶囊随滚动点亮——且胶囊条自身视口会跟随当前轮次保持可见 |
 | ⬆️⬇️ **滚动按钮** | 点击或悬停持续滚动；无可滚动内容时置灰 |
-| 🎛️ **胶囊条模式开关** | 设置 → 通用 → *轮次导航*：`DSH 官方` / `DSH STN`（默认）/ `全部隐藏`——跨刷新持久保存 |
+| 🎛️ **胶囊条模式开关** | 设置 → 通用 → *轮次导航*：`DSH 官方` / `DSH STN`（默认）/ `全部隐藏`——跨刷新持久保存，官方胶囊条终于可以**关掉** |
 | 🔌 **纯外部插件** | 不改 DSH 源码；零宿主改动；零新增依赖；仅只读 DOM |
 
 ## 与官方 DSH 轮次胶囊条对比
 
-官方内置 `TurnNavigator` **没有关闭开关**，始终渲染在会话视图里。DSH STN 是它的升级版：
+官方内置 `TurnNavigator` **没有关闭开关**，始终渲染在会话视图里。下表对比对象为 **dsh 0.1.3-alpha.1**（当前 DSH Web 的 `TurnNavigator`，该版也通过自己的宿主投影恢复了全会话范围）与本插件 **DSH STN v0.4.2**：
 
-| 能力 | DSH 官方胶囊条 | DSH STN |
+| 能力 | DSH 官方胶囊条（0.1.3-alpha.1） | DSH STN（v0.4.2） |
 |---|---|---|
-| 显示的轮次 | 仅**已加载窗口** | **全部持久化轮次**（全量历史） |
-| 跳转窗口外轮次 | ❌ 看不到也跳不了 | ✅ 按需扩展窗口 + 即时反馈 |
-| 长会话打开性能 | 窗口渲染 | **零 prepend**——不重渲染会话流、不卡顿 |
-| 滚动跟随高亮 | ✅ | ✅ |
-| 悬停预览 | prompt + response（各 ≤160 字符） | 序号 + 时间 + 完整摘要 Tooltip |
-| 波浪涟漪动画 | ❌ | ✅ |
-| 滚动按钮（点击 / 悬停持续） | ❌ | ✅ |
-| 胶囊条高度 | 固定区域按比例压缩（≤420px） | 自适应（≤30vh）+ 内部滚动 |
+| 显示的轮次 | **全部轮次**——宿主 `turnOutline` 投影（0.1.3+） | 全部持久化轮次——**客户端**读取 journal |
+| 全会话历史怎么读 | 宿主侧投影内嵌在会话快照里 | 客户端分页读持久化日志（`session/page`）；旧版 dsh 退回 `sessions.history` RPC——**零宿主改动** |
+| 跳转窗口外轮次 | ✅（0.1.3+ 未加载锚点按 seq 分页） | ✅ 按需扩展窗口 + "正在定位第 N 轮…"脉冲/气泡 |
+| 长会话打开性能 | 读投影 | **零 prepend**——纯数据、不重渲染会话流、不卡顿 |
+| 滚动跟随高亮 | ✅（0.1.3+ 让 active mark 保持在胶囊条视口内，带指针守卫） | ✅（v0.4.1+ 同款指针守卫跟随） |
+| 悬停预览 | prompt + response（各 ≤3 行），无时间戳 | 轮次号 + **时间戳** + 完整用户消息摘要 |
+| 波浪涟漪动画 | ❌（改为固定节距 tick 加宽） | ✅ 波浪涟漪 |
+| 滚动按钮（点击 / 悬停持续） | ❌（滚轮 + 渐隐） | ✅ 点击 / 悬停持续 |
+| 胶囊条高度 | 动态 band（自然高…420px） | 自适应（≤30vh）+ 内部隐藏滚动条 |
 | 窄窗口（<900px） | 自动隐藏 | 自动隐藏（与官方对齐） |
-| 隐藏 / 切换胶囊条 | ❌ 无开关 | ✅ 设置 → 通用 → 三档 |
-| 键盘可达 | ✅（焦点环） | ✅（按钮） |
+| **隐藏 / 切换胶囊条** | ❌ 无开关 | ✅ 设置 → 通用 → 三档；`全部隐藏` 两者皆隐 |
+| 键盘可达 | ✅ 焦点环 + `aria-current`/`aria-busy`/`aria-describedby` | ✅ 可聚焦按钮（aria-label=`Turn N — 时间 — 摘要`） |
 | 来源 | 内置、无法关闭 | 外部插件，**可替换 / 可关闭** |
 
+dsh 0.1.3 起官方胶囊条已在紧要的全会话范围与窗口外跳转上追平。**DSH STN 仍然独占的**：可以**关掉它**（官方关不掉）、Tooltip 带**时间戳与完整摘要**、**滚动按钮 + 波浪悬停**、以及它始终是**零宿主改动的外部只读插件**。在 dsh ≤ 0.1.2 上官方胶囊条更简单（仅加载窗口），DSH STN 填补的差距更大。
+
+## 版本对照
+
+我们的版本与 dsh 版本的对应关系：
+
+| DSH STN | dsh | 说明 |
+|---|---|---|
+| v0.1.x | dsh ≤ 0.1.1 | 通过旧版 `sessions.history` 浏览器→宿主 RPC 读全量历史 |
+| v0.2.x – v0.4.1 | dsh 0.1.2+ | 适配 `ui-chat` 重构；通过 journal `session/page` 通道读全量历史；v0.4.1 修复真实轮次号与胶囊条视口跟随 |
+| **v0.4.2** | dsh 0.1.2+（含 **0.1.3-alpha.1**） | 本版：对照 dsh 0.1.3 官方胶囊条更新对比与定位（见上文） |
+
+本文 README 的对比对象为 **dsh 0.1.3-alpha.1**；在更旧的 dsh 上官方胶囊条更简单，DSH STN 的优势更大。
+
 ## 安装
 
 ```sh
@@ -67,7 +82,7 @@ dsh web
 0. **选择显示哪个胶囊条**（设置 → 通用 → **轮次导航**）：`DSH 官方`（内置 rail）、`DSH STN`（本插件 rail——**默认**）、或`全部隐藏`。官方 rail 没有关闭开关，选择 DSH STN 时以样式覆盖将其隐藏，我们的 rail 接管右缘居中位置。选择会跨刷新持久保存。
 1. 打开任意包含至少一轮已完成轮次的会话。
 2. 会话右侧出现一条竖向灰色胶囊列（每轮一个）。胶囊条**长度自适应**：轮次少则短，轮次多则达 30vh 上限后内部滚动（滚动条隐藏，无布局抖动）。
-3. **悬停**某个胶囊：它以主题色亮起并泛起波浪、向左加宽，胶囊条左侧弹出 Tooltip（序号、时间、摘要），始终完整在视口内。
+3. **悬停**某个胶囊：它以主题色亮起并泛起波浪、向左加宽，胶囊条左侧弹出 Tooltip（**序号、时间、摘要**），始终完整在视口内。
 4. **点击**某个胶囊：会话滚动到该轮起点并短暂高亮目标行；窗口外轮次会先脉冲闪烁 + 弹出"正在定位第 N 轮…"气泡，按需扩展窗口后定位。被点击的胶囊自动滚动到胶囊条中央（首尾两条除外）。
 5. **滚动**：滚轮、上下按钮、或按住按钮持续滚动。
 
@@ -83,12 +98,12 @@ dsh web
 - **全量历史即数据**：dsh 0.1.2+ 上，胶囊条通过 Typert Remote `session/page` 通道分页读取与官方窗口同一条持久化日志（`ctx.remote.session`——由基础 web 装配挂载；**零宿主改动、零新增依赖**）；旧版 dsh 走 `sessions.history` RPC。每轮从 `turn/start` / `user/message` / `turn/end` 原始事件派生为纯数据。
 - **按需跳转**：点击窗口内轮次直接滚动；窗口外轮次通过官方会话 store 的 `loadOlder()` 逐页扩展窗口（以权威 `hasMore` 为终止条件）直到目标进入视图——这是唯一触碰会话流的路径，且只在点击时发生。
 - **精确定位**：取该轮第一个 chat-node key，通过 `data-chat-anchor-key` 找到 DOM 行，直接设置滚动容器 `scrollTop`（比 `scrollIntoView` 更可控）。
-- **取代官方胶囊条**：官方 rail 位于会话滚动容器内；模式开关驱动的容器限定样式规则将其隐藏，我们的 rail 接管右缘居中位置。若未来 dsh 改变该结构，最坏情况是官方 rail 重新出现（并存）——绝不会崩溃。
+- **取代官方胶囊条**：官方 rail 位于会话滚动容器内；模式开关驱动的容器限定样式规则将其隐藏，我们的 rail 接管右缘居中位置。已在结构层面核对 dsh 0.1.3-alpha.1——`[data-conversation-scroll] nav` 隐藏规则依然匹配。若未来 dsh 改变该结构，最坏情况是官方 rail 重新出现（并存）——绝不会崩溃。
 - **只读**：插件从不写入 DSH 状态、从不外发数据，仅读取 DOM 用于定位。
 
 ## 兼容性
 
-- DeepSeek Harness (dsh) Web 客户端（`dsh web`）。
+- DeepSeek Harness (dsh) Web 客户端（`dsh web`）；基于 dsh 0.1.2+ 开发与实测，并对照 dsh 0.1.3-alpha.1 复核。
 - 需要 `conversation.session.header.utilities` 与 `settings.general.item` slot 声明（当前 DSH 已包含）。
 - 默认 `DSH STN` 模式以样式覆盖隐藏官方 rail，我们的 rail 居中接管；`DSH 官方` 模式显示内置 rail；`全部隐藏` 两者皆隐。900px 以下都自动隐藏。
 - 与全屏插件页面（如看板）共存：胶囊条层级位于全屏 overlay 之下。
@@ -102,4 +117,4 @@ dsh web
 
 ## 许可证
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-turn-navigator",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "DSH Smoothly Turn Nav (DSH STN): full-history piano-key turn rail for DeepSeek Harness (dsh) web conversations — see every turn at a glance, hover to preview, click to jump anywhere, and replace the official (non-disableable) turn rail.",
   "type": "module",
   "main": "lib/index.js",