dsh-turn-navigator 0.1.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.4.0] - 2026-08-29
+
+### Added
+
+- **Rail display mode (Settings → General → Turn navigation)**: three-way choice between `DSH official` (the built-in rail), `DSH STN` (this plugin's rail — default), and `Hide all`. Registered into the official `settings.general.item` seat (root scope), styled like the built-in preference rows (EnterBehaviorRow pattern), persisted browser-locally (localStorage — the official `settingsScope` store needs a Host-registered namespace that an external client-only plugin has no seam to create).
+- **Subtractive takeover of the official rail**: the official built-in TurnNavigator has no off-switch, so in `DSH STN` mode it is hidden with a container-scoped stylesheet override (`body.tn-hide-official [data-conversation-scroll] nav { display: none !important }` — our rail is fixed OUTSIDE the conversation scroll container, so the rule cannot match ours), and our rail takes over the right-edge center position. `Hide all` hides both.
+- **Official-rail detection fix**: the old check matched `nav[aria-label*="轮次"/"Turn navigation"]` anywhere, which also matched OUR OWN rail (same localized label) — so the rail stayed nudged into the header zone even when the official rail was absent (e.g. 1-turn sessions). The check is now scoped to `[data-conversation-scroll]` and reads the COMPUTED display value, so the nudge follows reality: official visible → we nudge; official hidden by our override → we stay centered.
+- **Brand name**: DSH Smoothly Turn Nav (DSH STN) — used in the README, settings row, and changelog.
+
+# Changelog
+
+## [0.3.0] - 2026-08-29
+
+### Added
+
+- **Full history restored on dsh 0.1.2+ (journal channel)**: the 0.2.0 refactor removed the browser→host `sessions.history` RPC, so the rail degraded to loaded-window turns. This release restores the full-history rail in the browser with **zero host changes and zero new dependencies**: the plugin pages the same persisted log the official window reads through the Typert Remote `session/page` endpoint (`ctx.remote.session` — the namespace is mounted by the base web assembly into `ctx.get('remote.session')`, read without adding to the cordis `inject` list because `ctx.get` is the inject-free store read; the traced `ctx.get('remote').session` path would hit the "without inject" gate). Every persisted turn (including turns far outside the window) is shown as plain data, paged incrementally, with no prepends into the conversation flow on open — the same performance story as 0.1.x, now purely client-side.
+- **Official-store jump path**: window expansion for out-of-window jumps now goes through the official session store (`sessions.binding(id).session.loadOlder()`), with the authoritative `hasMore` from `binding(id).eventSource.getSnapshot().hasMore` as the loop terminator (no more DOM "Load earlier" button sniffing on 0.1.2+), and row polling instead of fixed sleeps so fast renders jump immediately. The "Load earlier" button path remains as a fallback on older hosts.
+- **Journal readiness wait**: the official session binding is staged a moment after the conversation view mounts; the full-history fetch now waits (bounded, 15s) for the window's seq bounds instead of silently skipping, so the rail fills with all turns shortly after open.
+
+### Changed
+
+- History-channel priority: 0.1.2+ journal (`session/page`) → legacy `sessions.history` RPC → window-only turns (each layer degrades gracefully, including when `remote.session` is not yet mounted at boot — handles are resolved lazily and retried at render).
+
+## [0.2.0] - 2026-08-29
+
+### Changed
+
+- **Adapted to dsh 0.1.2+ (ui-chat refactor)**: the conversation data model changed — `ConversationSnapshot` lost its `chat` field and the old `dsh-client-runtime` package was removed. The rail now reads turn data through the new `useChat` hook (ChatSnapshot, `navigation.items()`), falls back to the legacy `.chat`-wrapped snapshot on older dsh, and imports `ClientContext` from `@deepseek-ai/cordis` (with the `dsh-client-ui-renderer/client` merge for `ctx.slots`). This fixes the crash that hid the rail after upgrading.
+- **Coexists with the official built-in TurnNavigator**: the official dsh rail (in-chat, always rendered, cannot be disabled) now overlaps-free — when it is present our rail nudges up into the header zone (`.tn-nudge`) instead of the scrollport center. Mirrored the official narrow-viewport hide (`@media max-width: 900px`).
+- **Added follow-scroll active-turn highlight**: the capsule for the turn at the reading line is tinted (brand color) as you scroll — a capability the official rail has and we previously lacked.
+- **History-as-data is window-scoped on 0.1.2+**: the browser→host `sessions.history` RPC (`connection.api`) was removed in the refactor, so the full-history read is unavailable in the browser on new dsh; the rail degrades to the loaded-window turns (same data as the official rail) and keeps its UI/UX (wave hover, scroll buttons, center-on-click, tooltip, jump feedback, follow highlight). Full-history support is a known follow-up (host-half route) if desired.
+
 ## [0.1.1] - 2026-08-19
 
 ### Changed

package/README.md

@@ -1,19 +1,54 @@
-# dsh-turn-navigator
+# DSH Smoothly Turn Nav (DSH STN)
 
 **English · [简体中文](README.zh.md)**
 
-An external [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that adds a **piano-key turn rail** to the conversation interface — a vertical column of tiny capsules on the right edge of the conversation, one per turn, so you can see every turn at a glance, hover to preview it, and click to jump to its start.
+**Every turn of your conversation, one glance away.**
+
+DSH Smoothly Turn Nav (**DSH STN**) is an external plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) that puts a **piano-key turn rail** on the right edge of every conversation — a vertical column of tiny capsules, one per turn. It gives you a full minimap of the conversation: **every turn ever made** (not just the ones currently loaded), hover previews, click-to-jump to any turn's start, and follow-scroll highlighting. It can also **replace the official built-in turn rail**, which has no off-switch of its own.
 
 ![Turn navigation rail](docs/turn-nav-rail.png)
 
 ## Why
 
-In the default DSH web UI, finding a specific turn in a long conversation means scrolling — a lot. There's no overview of how many turns happened, what each turn was about, or where the current scroll position sits. `dsh-turn-navigator` solves this with a minimap-style rail:
-
-- A **vertical capsule per turn** floats on the right edge of the conversation (grey, ~3px tall, piano-key style).
-- **Hovering** a capsule makes it glow with the theme's primary label color and widen to 150% (the two neighbours widen to 125% too), so sliding across the rail ripples like a wave — and shows the full turn info (index, timestamp, user-message summary) in a native DSH tooltip.
-- **Clicking** a capsule scrolls the conversation to that turn's start and briefly highlights it.
-- **Every turn is shown as data, instantly**: the rail reads the full conversation history from the host (`sessions.history` RPC) as lightweight data — no prepends into the conversation flow, so even a 150-turn session opens without re-rendering the flow. Clicking a capsule for a turn outside the window extends the window on demand to reach it.
+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:
+
+- **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.
+- **Click to jump anywhere** — jumps to any turn's start, even turns not yet loaded (the window is extended on demand with instant feedback).
+- **Know where you are** — the current turn is highlighted as you scroll.
+
+## Features
+
+| | |
+|---|---|
+| 🗺️ **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 |
+| 🎯 **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 |
+| ⬆️⬇️ **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 |
+| 🔌 **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:
+
+| Capability | DSH official rail | DSH STN |
+|---|---|---|
+| 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 |
+| Narrow viewport (<900px) | Auto-hidden | Auto-hidden (mirrors official) |
+| Hide / switch rail | ❌ No off-switch | ✅ Settings → General → 3 modes |
+| Keyboard reachable | ✅ (focus ring) | ✅ (buttons) |
+| Source | Built-in, cannot be disabled | External plugin, **can be replaced/disabled** |
 
 ## Installation
 
@@ -29,31 +64,41 @@ dsh web
 
 ## Usage
 
+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 of the conversation (one capsule per turn). The rail **auto-sizes**: its length grows with the turn count, capped at **30vh** — a short conversation gets a short rail, a long one hits the cap and scrolls internally with a **hidden scrollbar** (no layout jitter). **Up/down scroll buttons** at its top and bottom support both click and **hover-hold auto-scroll**, and are greyed out when there is nothing to scroll in that direction — so the rail never stretches past the viewport, and you can wheel, click, or hold to move through the turns.
-3. Hover a capsule to see the turn's index, timestamp, and user-message summary in a DSH-style tooltip anchored to the left of the rail, vertically centered on the hovered capsule and always fully inside the viewport. The capsule glows with the theme color and widens 150% LEFTWARDS (right-aligned — the right edge never moves), with the two neighbours widening a little too, a wave ripple across the rail.
-4. Click a capsule to jump to that turn's start. If the turn is outside the conversation window, the rail shows immediate feedback — the clicked capsule pulses and a "Locating turn N…" bubble appears beside it — while the window is extended on demand; when the turn is in view it scrolls to it and briefly highlights the target row. The activated capsule also scrolls to the center of the rail unless it is the first or last turn.
-5. Every turn is visible immediately (read from history as data, without loading the flow); clicking a turn outside the conversation window loads just enough history to reach it.
+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.
+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.
 
 ## How it works
 
-The plugin registers **one additive slot** — **no DSH source code is modified**:
+The plugin registers **two additive slots** — **no DSH source code is modified**:
 
 | Slot | Scope | Role |
 |------|-------|------|
-| `conversation.session.header.utilities` | session | The floating turn rail; reads `useSession` directly |
-
-Because the rail is session-scoped, it reads the live `ConversationSnapshot` straight from the framework `useSession` kit and renders as `position: fixed` (so it does not occupy the header's flex row).
+| `conversation.session.header.utilities` | session | The floating turn rail (renders `position: fixed`; reads the live chat snapshot via the framework `useChat`/`useSession` kit) |
+| `settings.general.item` | root | The *Turn navigation* mode switch in Settings → General |
 
-- **Turn extraction**: the rail's full turn list comes from the browser→host `sessions.history` RPC (paged, incremental) — every persisted turn is derived as data (`turn/start` / `user/message` / `turn/end` events → turn number, timestamp, first user-message summary), including turns far outside the conversation window. The live window snapshot (`useSession` → `chat.timeline.turnOrder`) supplements the newest still-running turns. Turns without a user message fall back to their first node's kind.
-- **Jump-to-turn**: locate the turn's first chat-node key, find the DOM row via `data-chat-anchor-key="<key>"`, compute its position in the `[data-conversation-scroll]` scrollport, and set `scrollTop` precisely (more predictable than `scrollIntoView`). If the target row is not yet rendered (older page not loaded), it auto-clicks the "Load earlier" button and retries until the row appears — no "scroll once first" friction.
-- **History-as-data (no flow prepends on open)**: the conversation window only materializes a page of events as DOM, and extending it (`loadOlder`) re-renders the whole flow — expensive on long sessions. The rail instead reads the full persisted history through the browser→host `sessions.history` RPC (paged, incremental) and derives every turn as plain data, so opening a session never touches the flow DOM. **On demand**: clicking a capsule for a turn already in the window scrolls to it directly; for a turn outside the window, the rail extends the window page by page (clicking the "Load earlier" paging button, respecting its in-flight state) until that turn is in the window, then scrolls and highlights it — the only path that prepends into the flow, and it runs only when the user clicks.
+- **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.
+- **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`).
-- Requires the `conversation.session.header.utilities` slot declaration (present in current DSH).
-- Coexists with full-screen plugin pages (e.g. the kanban board): the rail sits below their overlay layer, so an open page always covers it.
+- 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.
+
+## Development
+
+- `pnpm typecheck` / `pnpm test` — TypeScript check (tsdown does not typecheck).
+- `pnpm bundle` — build the module-table client bundle into `lib/`.
+- `scripts/verify-*.mjs` — Playwright acceptance scripts against a live `dsh web` (rail, full-history journal, mode switch, jump, feedback, overlay, sizing, UI).
+- `pnpm release:check` — release gates (version, tag, tree, build, registry).
 
 ## License
 

package/README.zh.md

@@ -1,19 +1,54 @@
-# dsh-turn-navigator
+# DSH Smoothly Turn Nav（DSH STN）
 
 **[English](README.md) · 简体中文**
 
-一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 外部插件，为会话界面增加**钢琴键式轮次胶囊条**——在会话界面右侧悬浮一条竖向胶囊列，每轮一个小胶囊，让你一眼纵览整场会话有哪几轮，悬停预览，点击跳转到任意轮次起始点。
+**整场会话，一眼纵览。**
+
+DSH Smoothly Turn Nav（**DSH STN**）是 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的外部插件，在每条会话右侧放一条**钢琴键式轮次胶囊条**——竖向一列小胶囊，一轮一个。它是整场会话的迷你地图：**全部历史轮次一目了然**（不只是当前已加载的窗口），悬停预览、点击跳转到任意轮次起点、滚动跟随高亮。它还可以**取代官方内置轮次胶囊条**（官方没有自己的关闭开关）。
 
 ![轮次导航胶囊条](docs/turn-nav-rail.png)
 
 ## 为什么需要
 
-DSH Web UI 中，在长会话里找某一轮只能靠滚动——没有轮次概览，不知道有几轮、每轮说了什么、当前滚到哪里。`dsh-turn-navigator` 用类似 minimap 的胶囊条解决这个问题：
-
-- 会话界面右侧**悬浮一条竖向胶囊列**（每轮一个灰色小胶囊，约 3px 高，钢琴键式）。
-- **悬停**某个胶囊：该胶囊以**主题色**亮起并加宽 150%，相邻两个胶囊也稍微加宽（125%）——鼠标滑过时像波浪一样起伏；同时以 DSH 原生 Tooltip 完整展示该轮信息（序号、时间戳、用户消息摘要）。
-- **点击**某个胶囊：会话滚动到该轮起点并短暂高亮。
-- **全部轮次即时展示为数据**：胶囊条通过 host 的 `sessions.history` RPC 直接读取完整会话历史（轻量数据，**不 prepend 进会话流**）——即使 150 轮的会话，打开也不重渲染会话流。点击窗口外的轮次时才按需扩展窗口。
+DSH Web UI 的官方轮次胶囊条只显示**当前已加载窗口内**的轮次——长会话里，大部分轮次要滚动加载后才可见。DSH STN 解决这个问题：
+
+- **全量历史一眼可见**——所有持久化轮次以纯数据呈现，包括远在已加载窗口之外的轮次。不滚动、不加载、不等待。
+- **悬停即预览**——胶囊以主题色亮起并泛起波浪涟漪；DSH 风格 Tooltip 展示该轮序号、时间与用户消息摘要。
+- **点击跳转任意轮**——包括尚未加载的轮次（按需扩展窗口，带即时反馈）。
+- **随时知道自己在哪**——滚动时当前轮次高亮。
+
+## 特性
+
+| | |
+|---|---|
+| 🗺️ **全量历史迷你地图** | 所有轮次立即可见——从持久化会话日志以数据读取，**打开会话零 prepend**（长会话保持流畅） |
+| 🎹 **钢琴键设计** | 每轮一个约 3px 高的胶囊，右缘右对齐；长度自适应（上限 30vh），超出后内部滚动（滚动条隐藏） |
+| 🌊 **波浪悬停** | 悬停的胶囊以主题色亮起并向左加宽 150%，相邻两个加宽 125%——滑过时如波浪起伏 |
+| 💬 **丰富 Tooltip** | 轮次序号、时间戳、完整用户消息摘要，始终完整显示在视口内 |
+| 🎯 **跳转任意轮** | 精确 `scrollTop` 定位（不与 `scrollIntoView` 打架）；窗口外跳转按需扩展窗口并显示"正在定位第 N 轮…"脉冲+气泡；最老轮次跳转加载到**真正第一轮**（`hasMore = false`） |
+| 👁️ **滚动跟随高亮** | 阅读线所在轮次的胶囊随滚动点亮 |
+| ⬆️⬇️ **滚动按钮** | 点击或悬停持续滚动；无可滚动内容时置灰 |
+| 🎛️ **胶囊条模式开关** | 设置 → 通用 → *轮次导航*：`DSH 官方` / `DSH STN`（默认）/ `全部隐藏`——跨刷新持久保存 |
+| 🔌 **纯外部插件** | 不改 DSH 源码；零宿主改动；零新增依赖；仅只读 DOM |
+
+## 与官方 DSH 轮次胶囊条对比
+
+官方内置 `TurnNavigator` **没有关闭开关**，始终渲染在会话视图里。DSH STN 是它的升级版：
+
+| 能力 | DSH 官方胶囊条 | DSH STN |
+|---|---|---|
+| 显示的轮次 | 仅**已加载窗口** | **全部持久化轮次**（全量历史） |
+| 跳转窗口外轮次 | ❌ 看不到也跳不了 | ✅ 按需扩展窗口 + 即时反馈 |
+| 长会话打开性能 | 窗口渲染 | **零 prepend**——不重渲染会话流、不卡顿 |
+| 滚动跟随高亮 | ✅ | ✅ |
+| 悬停预览 | prompt + response（各 ≤160 字符） | 序号 + 时间 + 完整摘要 Tooltip |
+| 波浪涟漪动画 | ❌ | ✅ |
+| 滚动按钮（点击 / 悬停持续） | ❌ | ✅ |
+| 胶囊条高度 | 固定区域按比例压缩（≤420px） | 自适应（≤30vh）+ 内部滚动 |
+| 窄窗口（<900px） | 自动隐藏 | 自动隐藏（与官方对齐） |
+| 隐藏 / 切换胶囊条 | ❌ 无开关 | ✅ 设置 → 通用 → 三档 |
+| 键盘可达 | ✅（焦点环） | ✅（按钮） |
+| 来源 | 内置、无法关闭 | 外部插件，**可替换 / 可关闭** |
 
 ## 安装
 
@@ -29,31 +64,41 @@ dsh web
 
 ## 使用
 
-1. 打开任意有至少一轮完成的会话。
-2. 会话界面右侧出现一条竖向灰色胶囊列（每轮一个胶囊）。胶囊条**长度自适应**：随轮次多少自动增减，**上限 30vh**——轮次少时胶囊条短，轮次多时达到上限后内部滚动；滚动条隐藏（避免抖动）。上下各有一个**滚动按钮**：支持点击和**悬停持续自动滚动**，没有可滚动内容时自动置灰——轮次再多也不会超出浏览器范围。
-3. 悬停某个胶囊：胶囊**以主题色亮起并向左加宽 150%**（右对齐，右缘不动；相邻两个胶囊也稍微加宽——滑过时形成波浪波纹），胶囊条左侧弹出 DSH 风格 Tooltip，**垂直居中于悬停的胶囊**、始终完整在视口内，展示完整信息（序号、时间戳、用户消息摘要）。
-4. 点击某个胶囊：会话滚动到该轮起点（目标行短暂高亮），**该胶囊自动滚动到胶囊条中央**（首尾两条除外）。若目标轮在会话窗口之外，胶囊条会**立即给出反馈**——被点击的胶囊脉冲闪烁，胶囊条左侧弹出"正在定位第 N 轮…"气泡——按需扩展窗口；目标轮进入窗口后滚动定位并高亮。
-5. 所有轮次即时可见（从历史以数据形式读取，不加载会话流）；点击窗口外的轮次时，只加载到达那一轮所需的历史。
+0. **选择显示哪个胶囊条**（设置 → 通用 → **轮次导航**）：`DSH 官方`（内置 rail）、`DSH STN`（本插件 rail——**默认**）、或`全部隐藏`。官方 rail 没有关闭开关，选择 DSH STN 时以样式覆盖将其隐藏，我们的 rail 接管右缘居中位置。选择会跨刷新持久保存。
+1. 打开任意包含至少一轮已完成轮次的会话。
+2. 会话右侧出现一条竖向灰色胶囊列（每轮一个）。胶囊条**长度自适应**：轮次少则短，轮次多则达 30vh 上限后内部滚动（滚动条隐藏，无布局抖动）。
+3. **悬停**某个胶囊：它以主题色亮起并泛起波浪、向左加宽，胶囊条左侧弹出 Tooltip（序号、时间、摘要），始终完整在视口内。
+4. **点击**某个胶囊：会话滚动到该轮起点并短暂高亮目标行；窗口外轮次会先脉冲闪烁 + 弹出"正在定位第 N 轮…"气泡，按需扩展窗口后定位。被点击的胶囊自动滚动到胶囊条中央（首尾两条除外）。
+5. **滚动**：滚轮、上下按钮、或按住按钮持续滚动。
 
 ## 原理
 
-插件只注册**一个加法 slot**——**不修改 DSH 源码**：
+插件注册**两个加法 slot**——**不修改 DSH 源码**：
 
 | Slot | 作用域 | 职责 |
 |------|--------|------|
-| `conversation.session.header.utilities` | session | 悬浮轮次胶囊条；直接通过 `useSession` 读取 |
-
-因为胶囊条是 session 作用域，它直接从框架 `useSession` kit 读取实时 `ConversationSnapshot`，并以 `position: fixed` 渲染（不占据 header 的 flex 行）。
+| `conversation.session.header.utilities` | session | 悬浮轮次胶囊条（`position: fixed`；通过框架 `useChat`/`useSession` kit 读取实时会话快照） |
+| `settings.general.item` | root | 设置 → 通用 的 *轮次导航* 模式开关 |
 
-- **轮次提取**：胶囊条的完整轮次列表来自 browser→host 的 `sessions.history` RPC（分页、增量）——每一轮持久化轮次都以数据派生（`turn/start` / `user/message` / `turn/end` 事件 → 轮次号、时间戳、首条用户消息摘要），包括远在会话窗口之外的轮次。实时窗口快照（`useSession` → `chat.timeline.turnOrder`）补充最新的运行中轮次。无用户消息的轮次降级显示其首个节点的 kind。
-- **跳转定位**：取该轮第一个 chat-node key，通过 `data-chat-anchor-key="<key>"` 找到 DOM 行，在 `[data-conversation-scroll]` 滚动容器中精确计算并设置 `scrollTop`（比 `scrollIntoView` 更可控）。若目标行尚未渲染（更早页面未加载），自动点击"加载更早"按钮并重试直到行出现——无需先滚动一下。
-- **历史即数据（打开零 prepend）**：会话窗口只把一页事件物化为 DOM，扩展窗口（`loadOlder`）会重渲染整个会话流——长会话代价高。胶囊条改为通过 browser→host 的 `sessions.history` RPC 分页读取完整持久化历史，把每轮派生为纯数据，**打开会话完全不触碰会话流 DOM**。**按需加载**：点击窗口内轮次直接滚动；点击窗口外轮次时，胶囊条逐页扩展窗口（点击"加载更早"分页按钮，尊重其加载中状态）直到目标轮进入窗口，再滚动并高亮——这是唯一会 prepend 会话流的路径，且只在用户点击时发生。
+- **全量历史即数据**：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 重新出现（并存）——绝不会崩溃。
+- **只读**：插件从不写入 DSH 状态、从不外发数据，仅读取 DOM 用于定位。
 
 ## 兼容性
 
 - DeepSeek Harness (dsh) Web 客户端（`dsh web`）。
-- 需要 `conversation.session.header.utilities` slot 声明（当前 DSH 已包含）。
-- 与全屏插件页面（如看板）共存：胶囊条层级位于全屏 overlay 之下，打开全屏页面时会覆盖胶囊条。
+- 需要 `conversation.session.header.utilities` 与 `settings.general.item` slot 声明（当前 DSH 已包含）。
+- 默认 `DSH STN` 模式以样式覆盖隐藏官方 rail，我们的 rail 居中接管；`DSH 官方` 模式显示内置 rail；`全部隐藏` 两者皆隐。900px 以下都自动隐藏。
+- 与全屏插件页面（如看板）共存：胶囊条层级位于全屏 overlay 之下。
+
+## 开发
+
+- `pnpm typecheck` / `pnpm test` — TypeScript 检查（tsdown 只转译不检查）。
+- `pnpm bundle` — 构建模块表 client bundle 到 `lib/`。
+- `scripts/verify-*.mjs` — 针对真实 `dsh web` 的 Playwright 验收脚本（rail、全量历史 journal、模式开关、跳转、反馈、overlay、尺寸、UI）。
+- `pnpm release:check` — 发布门禁（版本、tag、工作树、构建、registry）。
 
 ## 许可证
 

package/lib/client.js

@@ -20,19 +20,37 @@ window.__ModuleLoader__.load({
 			return "";
 		}
 		/**
-		* Derive the flat turn list from a conversation snapshot.
+		* Derive the flat turn list from a chat snapshot.
 		*
 		* For each turn in `timeline.turnOrder`, the function looks up the turn's
 		* chat-node keys via `locations.getTurn`, finds the first node whose `kind`
 		* is `'user'`, and extracts the text summary from its content blocks. The
-		* timestamp comes from `turnTimings` (preferred) or `turn.start.time`.
+		* timestamp comes from `legacy.turnTimings` (preferred) or `turn.start.time`.
 		*
-		* @param snap - the conversation snapshot (structural subset).
+		* Accepts BOTH the new (0.1.2+) ChatSnapshot (from `useChat`) and the legacy
+		* `ConversationSnapshot` (which had a `.chat` field) — so an upgrade never
+		* crashes if the host is still on the older shape.
+		*
+		* @param snap - the chat snapshot (structural subset).
 		* @returns ordered turn entries (empty when the snapshot has no turns).
 		*/
 		function extractTurns(snap) {
-			if (snap === void 0) return [];
-			const chat = snap.chat;
+			const chat = unwrapChat(snap);
+			if (chat === void 0) return [];
+			const turnTimings = chat.legacy?.turnTimings ?? (snap !== void 0 && "turnTimings" in snap ? snap.turnTimings : void 0);
+			const navItems = chat.navigation?.items?.() ?? [];
+			if (navItems.length > 0) return navItems.map((item, index) => {
+				const loc = chat.timeline.turns.get(item.turn);
+				const status = loc?.status ?? "closed";
+				return {
+					turn: item.turn,
+					index: index + 1,
+					summary: item.prompt || "(no user message)",
+					fullText: item.prompt || "",
+					startTime: turnTimings?.get(item.turn)?.startTime ?? loc?.start?.time,
+					status
+				};
+			});
 			const timeline = chat.timeline;
 			const turnOrder = timeline.turnOrder;
 			if (turnOrder.length === 0) return [];
@@ -42,7 +60,7 @@ window.__ModuleLoader__.load({
 				displayIndex += 1;
 				const loc = timeline.turns.get(turn);
 				const status = loc?.status ?? "unknown";
-				const startTime = snap.turnTimings.get(turn)?.startTime ?? loc?.start?.time;
+				const startTime = turnTimings?.get(turn)?.startTime ?? loc?.start?.time;
 				let summary = "";
 				let fullText = "";
 				const keys = chat.locations.getTurn(turn);
@@ -74,6 +92,12 @@ window.__ModuleLoader__.load({
 			}
 			return entries;
 		}
+		/** Narrow either the new ChatSnapshot or the legacy `.chat`-wrapped snapshot to a chat. */
+		function unwrapChat(snap) {
+			if (snap === void 0) return void 0;
+			if ("chat" in snap && snap.chat !== void 0) return snap.chat;
+			return snap;
+		}
 		/** Best-effort text peek from a non-user chat node's data (erased shape). */
 		function peekNodeText(node) {
 			const data = node.data;
@@ -109,14 +133,36 @@ window.__ModuleLoader__.load({
 		* @returns the first node key in that turn (typically the user message), or undefined.
 		*/
 		function firstNodeKeyOfTurn(snap, turn) {
-			if (snap === void 0) return void 0;
-			return snap.chat.locations.getTurn(turn)[0];
+			const chat = unwrapChat(snap);
+			if (chat === void 0) return void 0;
+			return chat.locations.getTurn(turn)[0];
+		}
+		/**
+		* Reverse-lookup: given a chat-node key, find which turn it belongs to.
+		*
+		* Used by the scroll-follow highlight: the scroll listener finds the topmost
+		* visible `[data-chat-anchor-key]` row, then this function maps its key back
+		* to a turn number so the drawer can highlight the matching entry.
+		*
+		* @param snap - the conversation snapshot.
+		* @param key - the chat-node key from the DOM anchor.
+		* @returns the owning turn number, or undefined if not found.
+		*/
+		function turnOfNodeKey(snap, key) {
+			const chat = unwrapChat(snap);
+			if (chat === void 0) return void 0;
+			const { turnOrder, turns } = chat.timeline;
+			for (const turn of turnOrder) if (chat.locations.getTurn(turn).includes(key)) return turn;
 		}
 		//#endregion
 		//#region src/client/history.ts
 		const SUMMARY_MAX_CHARS = 80;
 		/** Safety cap on history pages read (50 events each). */
 		const MAX_HISTORY_PAGES = 500;
+		/** Journal page size in MESSAGES (user/assistant count) — no host cap, fewer round trips. */
+		const JOURNAL_PAGE_MESSAGES = 200;
+		/** Safety cap on journal pages read. */
+		const MAX_JOURNAL_PAGES = 100;
 		function firstText(content) {
 			if (content === void 0) return "";
 			for (const block of content) if (block.type === "text" && typeof block.text === "string") return block.text;
@@ -138,6 +184,10 @@ window.__ModuleLoader__.load({
 		* @param onPage - incremental callback (turns so far, in ascending turn order).
 		*/
 		async function fetchAllTurns(api, sessionId, onPage) {
+			if (api === void 0 || typeof api.sessions?.history !== "function") {
+				console.warn("[dsh-turn-nav] sessions.history RPC unavailable — falling back to window-only turns");
+				return [];
+			}
 			const allEvents = [];
 			let beforeSeq;
 			for (let page = 0; page < MAX_HISTORY_PAGES; page += 1) {
@@ -146,7 +196,10 @@ window.__ModuleLoader__.load({
 					beforeSeq,
 					maxMessages: 50
 				});
-				if (response.result === void 0 || response.result.ok !== true) break;
+				if (response.result === void 0 || response.result.ok !== true) {
+					console.warn("[dsh-turn-nav] sessions.history page failed", response.error?.code ?? "no result");
+					break;
+				}
 				const value = response.result.value;
 				if (value === void 0) break;
 				const { events, hasMore } = value;
@@ -161,6 +214,59 @@ window.__ModuleLoader__.load({
 			onPage(turns);
 			return turns;
 		}
+		/**
+		* Read the FULL persisted history through the 0.1.2+ journal channel
+		* (`ctx.remote.session.page`), newest page first, walking back via `beforeSeq`
+		* until `hasMore` is false. Only events BELOW the loaded window are fetched
+		* (the window itself already covers the tail), so the conversation flow is
+		* never touched — this is what keeps very long sessions responsive.
+		*
+		* Returns `undefined` when the journal channel is unavailable (older dsh), so
+		* the caller can fall back to the legacy `sessions.history` RPC or to
+		* window-only turns.
+		*
+		* @param journal - the mounted journal namespace face, or undefined.
+		* @param sessionId - the session to read.
+		* @param window - oldest/newest event seq of the currently loaded window.
+		* @param onPage - incremental callback (turns derived so far, ascending).
+		* @param signal - optional caller cancellation.
+		*/
+		async function fetchJournalTurns(journal, sessionId, window, onPage, signal) {
+			if (journal === void 0 || typeof journal.page !== "function") return void 0;
+			if (window.lastSeq === void 0 || window.firstSeq === 0) return [];
+			const before0 = window.firstSeq !== void 0 && window.firstSeq > 0 ? window.firstSeq - 1 : void 0;
+			if (before0 === void 0) return [];
+			const allEvents = [];
+			let beforeSeq = before0;
+			for (let page = 0; page < MAX_JOURNAL_PAGES; page += 1) {
+				if (signal?.aborted) break;
+				const result = await journal.page({
+					address: {
+						kind: "session",
+						sessionId
+					},
+					throughSeq: window.lastSeq,
+					beforeSeq,
+					maxMessages: JOURNAL_PAGE_MESSAGES
+				}, signal);
+				if (!result.ok || result.value === void 0) {
+					console.warn("[dsh-turn-nav] session/page failed", result.error?.code ?? "no result");
+					break;
+				}
+				const { records, hasMore } = result.value;
+				if (records.length === 0) break;
+				for (const record of records) if (record.type === "event") allEvents.push(record.event);
+				onPage(buildTurns(allEvents));
+				if (!hasMore) break;
+				let minSeq = Infinity;
+				for (const record of records) minSeq = Math.min(minSeq, record.event.seq);
+				if (!Number.isFinite(minSeq)) break;
+				beforeSeq = minSeq;
+			}
+			const turns = buildTurns(allEvents);
+			onPage(turns);
+			return turns;
+		}
 		/** Fold a (seq-ascending) event list into ordered turns. */
 		function buildTurns(events) {
 			const sorted = [...events].sort((a, b) => a.seq - b.seq);
@@ -211,6 +317,61 @@ window.__ModuleLoader__.load({
 			};
 		}
 		//#endregion
+		//#region src/client/mode.ts
+		/** localStorage key owning the persisted mode. */
+		const STORAGE_KEY = "dsh-turn-navigator.mode";
+		/** Default mode: our rail, official rail hidden (subtractive takeover). */
+		const DEFAULT_MODE = "stn";
+		const MODES = [
+			"stn",
+			"official",
+			"hidden"
+		];
+		/** Module-level current mode (stable reference for useSyncExternalStore). */
+		let current = readStored();
+		const listeners = /* @__PURE__ */ new Set();
+		function readStored() {
+			try {
+				const raw = window.localStorage.getItem(STORAGE_KEY);
+				if (MODES.includes(raw)) return raw;
+			} catch {}
+			return DEFAULT_MODE;
+		}
+		/** Read the current rail mode (useSyncExternalStore getSnapshot). */
+		function getRailMode() {
+			return current;
+		}
+		/** Subscribe to rail-mode changes (useSyncExternalStore subscribe). */
+		function subscribeRailMode(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+		/** Persist and publish a new rail mode. */
+		function setRailMode(mode) {
+			if (mode === current) return;
+			current = mode;
+			try {
+				window.localStorage.setItem(STORAGE_KEY, mode);
+			} catch {}
+			applyModeToBody();
+			for (const listener of [...listeners]) try {
+				listener();
+			} catch {}
+		}
+		/**
+		* Sync the `tn-hide-official` body class with the current mode. The class
+		* drives the stylesheet rule that hides the OFFICIAL rail (our rail is hidden
+		* by React instead). The official rail is hidden in every mode except
+		* `official` (where the user chose to see it). Called at plugin apply (body
+		* exists by then) and on every mode change.
+		*/
+		function applyModeToBody() {
+			if (typeof document === "undefined") return;
+			document.body.classList.toggle("tn-hide-official", current !== "official");
+		}
+		//#endregion
 		//#region src/client/TurnNavRail.tsx
 		/**
 		* Turn navigation rail: a vertical "piano-key" rail floating on the right
@@ -241,6 +402,8 @@ window.__ModuleLoader__.load({
 		const LOAD_RENDER_SETTLE_MS = 900;
 		/** Cap on pages loaded while expanding the window to a clicked turn. */
 		const MAX_JUMP_PAGES = 100;
+		/** Bounded wait for the official session binding/window to appear on mount. */
+		const JOURNAL_BINDING_WAIT_MS = 15e3;
 		/** Extra vertical margin when scrolling a target row into view. */
 		const JUMP_MARGIN_PX = 16;
 		/** Localized "Load earlier" paging button labels — idle AND in-flight. */
@@ -300,11 +463,12 @@ window.__ModuleLoader__.load({
 		* and renders a floating vertical capsule per turn (full history read from
 		* the host as data; the flow window is extended only on click-to-jump).
 		*/
-		function TurnNavRail({ useSession, sessionId, t, api }) {
-			const snapshot = useSession?.((s) => s);
-			const snapshotRef = (0, react.useRef)(snapshot);
-			snapshotRef.current = snapshot;
-			const windowTurns = (0, react.useMemo)(() => extractTurns(snapshot), [snapshot]);
+		function TurnNavRail({ useSession, useChat, sessionId, t, api, journal, sessionAccess }) {
+			const legacySession = useSession?.((s) => s);
+			const chat = useChat?.((c) => c);
+			const chatRef = (0, react.useRef)(chat ?? legacySession);
+			chatRef.current = chat ?? legacySession;
+			const windowTurns = (0, react.useMemo)(() => extractTurns(chat ?? legacySession), [chat, legacySession]);
 			const [historyTurns, setHistoryTurns] = (0, react.useState)([]);
 			const [hoverIndex, setHoverIndex] = (0, react.useState)(-1);
 			const [hoverY, setHoverY] = (0, react.useState)(0);
@@ -312,27 +476,112 @@ window.__ModuleLoader__.load({
 			const [canScrollUp, setCanScrollUp] = (0, react.useState)(false);
 			const [canScrollDown, setCanScrollDown] = (0, react.useState)(false);
 			const [jumpState, setJumpState] = (0, react.useState)(null);
+			const [officialRail, setOfficialRail] = (0, react.useState)(false);
 			const railRef = (0, react.useRef)(null);
 			const tipRef = (0, react.useRef)(null);
 			const hoverScrollRef = (0, react.useRef)(null);
 			(0, react.useEffect)(() => {
-				if (api === void 0 || sessionId === void 0) return;
-				let cancelled = false;
-				fetchAllTurns(api, sessionId, (pageTurns) => {
-					if (!cancelled) setHistoryTurns(pageTurns);
-				}).then((finalTurns) => {
-					if (!cancelled) setHistoryTurns(finalTurns);
+				let timer = null;
+				const check = () => {
+					const scroll = document.querySelector("[data-conversation-scroll]");
+					const nav = scroll === null ? null : scroll.querySelector("nav[aria-label*=\"轮次\"], nav[aria-label*=\"Turn navigation\"]");
+					const visible = nav !== null && getComputedStyle(nav).display !== "none";
+					setOfficialRail((prev) => prev === visible ? prev : visible);
+				};
+				check();
+				timer = setInterval(check, 1500);
+				const scroll = document.querySelector("[data-conversation-scroll]");
+				const observer = scroll !== null && typeof MutationObserver !== "undefined" ? new MutationObserver(check) : null;
+				if (observer !== null && scroll !== null) observer.observe(scroll, {
+					childList: true,
+					subtree: true
 				});
+				return () => {
+					if (timer !== null) clearInterval(timer);
+					observer?.disconnect();
+				};
+			}, []);
+			(0, react.useEffect)(() => {
+				if (sessionId === void 0) return;
+				let cancelled = false;
+				const applyPage = (turns) => {
+					if (!cancelled) setHistoryTurns(turns);
+				};
+				const run = async () => {
+					let window = sessionAccess?.windowSeq(sessionId) ?? {
+						firstSeq: void 0,
+						lastSeq: void 0
+					};
+					if (sessionAccess !== void 0) {
+						const deadline = Date.now() + JOURNAL_BINDING_WAIT_MS;
+						while (window.lastSeq === void 0 && Date.now() < deadline) {
+							await sleep(300);
+							if (cancelled) return;
+							window = sessionAccess.windowSeq(sessionId);
+						}
+					}
+					const journalTurns = await fetchJournalTurns(journal, sessionId, window, applyPage);
+					if (cancelled) return;
+					if (journalTurns !== void 0) {
+						setHistoryTurns(journalTurns);
+						return;
+					}
+					if (api !== void 0) await fetchAllTurns(api, sessionId, applyPage).then((finalTurns) => {
+						if (!cancelled) setHistoryTurns(finalTurns);
+					});
+				};
+				run();
 				return () => {
 					cancelled = true;
 				};
-			}, [api, sessionId]);
+			}, [
+				api,
+				journal,
+				sessionAccess,
+				sessionId
+			]);
+			const railMode = (0, react.useSyncExternalStore)(subscribeRailMode, getRailMode);
 			const turns = (0, react.useMemo)(() => {
 				if (historyTurns.length === 0) return windowTurns;
 				const historySet = new Set(historyTurns.map((entry) => entry.turn));
 				const extras = windowTurns.filter((entry) => !historySet.has(entry.turn));
 				return [...historyTurns, ...extras].sort((a, b) => a.turn - b.turn);
 			}, [historyTurns, windowTurns]);
+			const [activeTurn, setActiveTurn] = (0, react.useState)(null);
+			(0, react.useEffect)(() => {
+				const scroll = document.querySelector("[data-conversation-scroll]");
+				if (scroll === null) return;
+				let frame = null;
+				const compute = () => {
+					frame = null;
+					const scrollport = document.querySelector("[data-conversation-scroll]");
+					if (scrollport === null) return;
+					const rect = scrollport.getBoundingClientRect();
+					const readingLine = rect.top + Math.min(96, rect.height * .2);
+					const rows = Array.from(scrollport.querySelectorAll("[data-chat-anchor-key]"));
+					let row = null;
+					for (const r of rows) {
+						const rr = r.getBoundingClientRect();
+						if (rr.bottom > readingLine && rr.top < rect.bottom) {
+							row = r;
+							break;
+						}
+					}
+					const key = row?.getAttribute("data-chat-anchor-key") ?? null;
+					if (key !== null) setActiveTurn(turnOfNodeKey(chatRef.current, key) ?? null);
+					else if (rows.length > 0) setActiveTurn(null);
+				};
+				const schedule = () => {
+					if (frame !== null) return;
+					frame = requestAnimationFrame(compute);
+				};
+				scroll.addEventListener("scroll", schedule, { passive: true });
+				schedule();
+				return () => {
+					scroll.removeEventListener("scroll", schedule);
+					if (frame !== null) cancelAnimationFrame(frame);
+				};
+			}, [turns.length]);
 			(0, react.useEffect)(() => {
 				const rail = railRef.current;
 				if (rail === null) return;
@@ -404,16 +653,51 @@ window.__ModuleLoader__.load({
 					row.classList.add(HIGHLIGHT_CLASS);
 					setTimeout(() => row.classList.remove(HIGHLIGHT_CLASS), 1500);
 				};
+				const waitForRow = async (timeoutMs) => {
+					const deadline = Date.now() + timeoutMs;
+					while (Date.now() < deadline) {
+						const snap = chatRef.current;
+						const key = snap === void 0 ? void 0 : firstNodeKeyOfTurn(snap, turn);
+						if (key !== void 0) {
+							const row = scrollport.querySelector(`[${ANCHOR_ATTR}="${CSS.escape(key)}"]`);
+							if (row !== null) return row;
+						}
+						await sleep(80);
+					}
+					return null;
+				};
+				const settled = (row) => {
+					if (row === null) return false;
+					if (!isOldest) return true;
+					return !(sessionAccess !== void 0 ? sessionAccess.hasMore(sessionId ?? "") : findLoadOlderButton() !== null);
+				};
 				for (let i = 0; i < MAX_JUMP_PAGES; i += 1) {
-					const snap = snapshotRef.current;
+					const snap = chatRef.current;
 					const key = snap === void 0 ? void 0 : firstNodeKeyOfTurn(snap, turn);
 					const row = key === void 0 ? null : scrollport.querySelector(`[${ANCHOR_ATTR}="${CSS.escape(key)}"]`);
-					if (row !== null) {
-						const more = findLoadOlderButton();
-						if (!isOldest || more === null) {
-							scrollToRow(row);
+					if (settled(row)) {
+						scrollToRow(row);
+						return true;
+					}
+					if (sessionAccess !== void 0) {
+						if (!sessionAccess.hasMore(sessionId ?? "")) {
+							if (row !== null) {
+								scrollToRow(row);
+								return true;
+							}
+							return false;
+						}
+						try {
+							await sessionAccess.loadOlder(sessionId ?? "");
+						} catch {
+							return row !== null ? (scrollToRow(row), true) : false;
+						}
+						const awaited = await waitForRow(LOAD_RENDER_SETTLE_MS);
+						if (awaited !== null && settled(awaited)) {
+							scrollToRow(awaited);
 							return true;
 						}
+						continue;
 					}
 					const btn = findLoadOlderButton();
 					if (btn === null) {
@@ -452,9 +736,9 @@ window.__ModuleLoader__.load({
 					}
 				});
 			};
-			if (turns.length === 0) return null;
+			if (turns.length === 0 || railMode !== "stn") return null;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-				className: "tn-wrap",
+				className: `tn-wrap${officialRail ? " tn-nudge" : ""}`,
 				role: "navigation",
 				"aria-label": t("rail"),
 				onMouseLeave: () => {
@@ -481,9 +765,10 @@ window.__ModuleLoader__.load({
 							const dist = hoverIndex === -1 ? Infinity : Math.abs(i - hoverIndex);
 							const cls = dist === 0 ? " tn-cap-hot" : dist === 1 ? " tn-cap-warm" : "";
 							const loading = jumpState !== null && jumpState.phase === "loading" && jumpState.turn === entry.turn;
+							const isActive = activeTurn === entry.turn;
 							return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								type: "button",
-								className: `tn-cap-btn${cls}${loading ? " tn-loading" : ""}`,
+								className: `tn-cap-btn${cls}${loading ? " tn-loading" : ""}${isActive ? " tn-cap-active" : ""}`,
 								onMouseEnter: (e) => {
 									setHoverIndex(i);
 									const rect = e.currentTarget.getBoundingClientRect();
@@ -534,15 +819,94 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region src/client/SettingsNavModeRow.tsx
+		/**
+		* Settings → General row: WHICH turn-navigation rail to show.
+		*
+		* Registered into `settings.general.item` (root scope) by the plugin's apply;
+		* the General section renders each contribution as one row, so this component
+		* draws its own title, description, and a three-way selector:
+		*
+		*   DSH official | DSH STN (Smoothly Turn Nav) | Hide all
+		*
+		* The choice is persisted browser-locally (see mode.ts) and drives both the
+		* rail component (React-side visibility) and the official-rail stylesheet
+		* override (body class).
+		*/
+		const OPTIONS = [
+			{
+				id: "official",
+				label: "modeOfficial"
+			},
+			{
+				id: "stn",
+				label: "modeSTN"
+			},
+			{
+				id: "hidden",
+				label: "modeHidden"
+			}
+		];
+		/** Render the rail display-mode preference row. */
+		function SettingsNavModeRow({ t }) {
+			const mode = (0, react.useSyncExternalStore)(subscribeRailMode, getRailMode);
+			const [open, setOpen] = (0, react.useState)(false);
+			const selectedLabel = OPTIONS.find((option) => option.id === mode)?.label ?? "modeSTN";
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "tn-mode-row",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "tn-mode-row-text",
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "tn-mode-title",
+						children: t("modeRowTitle")
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "tn-mode-desc",
+						children: t("modeRowDesc")
+					})]
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Menu, {
+					open,
+					onClose: () => {
+						setOpen(false);
+					},
+					items: OPTIONS.map((option) => ({
+						id: option.id,
+						label: t(option.label)
+					})),
+					selectedId: mode,
+					onSelect: (id) => {
+						setOpen(false);
+						setRailMode(id);
+					},
+					align: "end",
+					portal: true,
+					anchor: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+						type: "button",
+						className: "tn-mode-selector",
+						"aria-haspopup": "menu",
+						"aria-expanded": open,
+						onClick: () => {
+							setOpen((value) => !value);
+						},
+						children: [t(selectedLabel), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutline14, { className: "tn-mode-chevron" })]
+					})
+				})]
+			});
+		}
+		//#endregion
 		//#region src/client/locales.ts
-		/** Copy dictionaries for the dsh-turn-navigator plugin. */
+		/** Copy dictionaries for the dsh-turn-navigator plugin (DSH Smoothly Turn Nav). */
 		/** English strings (the key-set source of truth for this pair). */
 		const en = {
 			rail: "Turn navigation",
 			turnLabel: "Turn {n}",
 			noSummary: "(no user message)",
 			locatingTurn: "Locating turn {n}…",
-			locateFailed: "Could not locate turn {n}"
+			locateFailed: "Could not locate turn {n}",
+			modeRowTitle: "Turn navigation",
+			modeRowDesc: "Which turn-navigation rail to display: the DSH built-in, DSH STN (Smoothly Turn Nav), or none.",
+			modeOfficial: "DSH official",
+			modeSTN: "DSH STN",
+			modeHidden: "Hide all"
 		};
 		/** Chinese strings (same keys as {@link en}). */
 		const zh = {
@@ -550,7 +914,12 @@ window.__ModuleLoader__.load({
 			turnLabel: "第 {n} 轮",
 			noSummary: "（无用户消息）",
 			locatingTurn: "正在定位第 {n} 轮…",
-			locateFailed: "无法定位第 {n} 轮"
+			locateFailed: "无法定位第 {n} 轮",
+			modeRowTitle: "轮次导航",
+			modeRowDesc: "选择显示哪个轮次胶囊条：DSH 官方、DSH STN（Smoothly Turn Nav），或全部隐藏。",
+			modeOfficial: "DSH 官方",
+			modeSTN: "DSH STN",
+			modeHidden: "全部隐藏"
 		};
 		//#endregion
 		//#region src/client/styles.ts
@@ -583,6 +952,81 @@ window.__ModuleLoader__.load({
   z-index: 10;
   pointer-events: auto;
 }
+/* When the built-in (official) TurnNavigator rail is present in the transcript
+   (right edge, vertically centered on the scrollport band), nudge our rail up
+   into the header zone so the two never overlap: same right edge, but pinned
+   below the session header instead of the scrollport center. */
+.tn-wrap.tn-nudge {
+  top: 64px;
+  transform: none;
+  max-height: calc(100vh - 140px);
+}
+/* Narrow viewport: mirror the official rail's @container (max-width: 900px)
+   hide, so we never fight the compact layout for the right edge. */
+@media (max-width: 900px) {
+  .tn-wrap {
+    display: none;
+  }
+}
+/* Subtractive takeover (settings → Turn navigation = DSH STN): hide the
+   OFFICIAL built-in rail. The official rail lives inside the conversation
+   scroll container (data-conversation-scroll) — our rail is fixed outside
+   it — so a container-scoped rule cannot match ours. The tn-hide-official
+   body class is toggled by mode.ts; the official rail itself has no
+   off-switch, so this stylesheet override is the only way to replace it. */
+body.tn-hide-official [data-conversation-scroll] nav {
+  display: none !important;
+}
+/* Settings → General preference row (which rail to show). Mirrors the official
+   EnterBehaviorRow tokens. */
+.tn-mode-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 16px 0;
+  border-bottom: 1px solid var(--dsw-alias-border-l2);
+}
+.tn-mode-row-text {
+  flex: 1;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding-right: 48px;
+}
+.tn-mode-title {
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+.tn-mode-desc {
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary);
+}
+.tn-mode-selector {
+  display: inline-flex;
+  align-items: center;
+  gap: 12px;
+  height: 36px;
+  padding: 0 14px;
+  border: none;
+  border-radius: 18px;
+  background: var(--dsw-alias-bg-module-platform);
+  font: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+  cursor: pointer;
+}
+.tn-mode-selector:hover {
+  background: var(--dsw-alias-interactive-bg-hover);
+}
+.tn-mode-chevron {
+  flex: none;
+}
 /* Up/down scroll controls at the top and bottom of the rail. Disabled (grey,
    no pointer/hover-scroll) when there is nothing to scroll in that
    direction. */
@@ -673,6 +1117,12 @@ window.__ModuleLoader__.load({
   transform: scaleX(1.25);
   background: var(--dsw-alias-label-secondary);
 }
+/* Active (current) turn following the scroll: a persistent brand tint so the
+   reader always knows where they are in the rail, distinct from hover. */
+.tn-cap-btn.tn-cap-active .tn-cap {
+  background: var(--dsw-alias-state-business-primary);
+  width: 14px;
+}
 /* Custom tooltip bubble: mirrors the DSH tooltip visual (dark plate, white
    text, pre-line for multi-line info), fixed-positioned to the LEFT of the
    rail so it never falls outside the browser window. */
@@ -791,15 +1241,61 @@ window.__ModuleLoader__.load({
 			}), "dsh-turn-navigator: copy dictionaries");
 			const t = ctx.locale.bind(NS);
 			const api = ctx.get("connection")?.api;
+			applyModeToBody();
+			let journal;
+			let sessionAccess;
+			const resolveHandles = () => {
+				if (journal !== void 0 && sessionAccess !== void 0) return;
+				const sessionNamespace = ctx.get("remote.session");
+				if (journal === void 0 && typeof sessionNamespace?.page === "function") journal = { page: (request, signal) => sessionNamespace.page(request, signal) };
+				if (sessionAccess === void 0) {
+					const sessionsService = ctx.get("sessions");
+					if (sessionsService !== void 0 && typeof sessionsService.binding === "function") sessionAccess = {
+						windowSeq(sessionId) {
+							const entries = sessionsService.binding?.(sessionId)?.eventSource?.getSnapshot?.()?.entries ?? [];
+							return {
+								firstSeq: entries[0]?.event?.seq,
+								lastSeq: entries.at(-1)?.event?.seq
+							};
+						},
+						hasMore(sessionId) {
+							return sessionsService.binding?.(sessionId)?.eventSource?.getSnapshot?.()?.hasMore ?? false;
+						},
+						async loadOlder(sessionId) {
+							const face = sessionsService.binding?.(sessionId)?.session;
+							if (face === void 0 || typeof face.loadOlder !== "function") return false;
+							try {
+								await face.loadOlder();
+								return true;
+							} catch {
+								return false;
+							}
+						}
+					};
+				}
+			};
+			resolveHandles();
+			ctx.slots.inject("settings.general.item", () => ctx.slots.register({
+				name: "settings.general.item",
+				id: "dsh-turn-navigator-mode",
+				order: 30,
+				locale: NS,
+				inject: () => ({ t })
+			}, SettingsNavModeRow));
 			ctx.slots.inject("conversation.session.header.utilities", () => ctx.slots.register({
 				name: "conversation.session.header.utilities",
 				id: "dsh-turn-navigator",
 				order: 20,
 				locale: NS,
-				inject: () => ({
-					t,
-					api
-				})
+				inject: () => {
+					resolveHandles();
+					return {
+						t,
+						api,
+						journal,
+						sessionAccess
+					};
+				}
 			}, TurnNavRail));
 		}
 		//#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-turn-navigator",
-  "version": "0.1.1",
-  "description": "External DeepSeek Harness plugin: a turn-navigation drawer that lists every conversation turn (user message summary + timestamp), jumps to any turn's start, and highlights the current turn as you scroll.",
+  "version": "0.4.0",
+  "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",
   "exports": {
@@ -62,7 +62,11 @@
     "turn",
     "navigation",
     "conversation",
-    "outline"
+    "outline",
+    "turn-rail",
+    "turn-navigator",
+    "smoothly-turn-nav",
+    "stn"
   ],
   "author": "karoc",
   "license": "MIT",