dsh-turn-navigator 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.1.1] - 2026-08-19
+
+### Changed
+
+- **History-as-data architecture (fixes stalls on very long sessions)**: the rail's turn list is now read from the HOST through the browser→host `sessions.history` RPC — every persisted turn (including ones far outside the conversation window) is shown as plain data, paged incrementally, with **zero prepends into the conversation flow on open**. Previously the rail extended the flow window by auto-clicking "Load earlier", which re-renders the whole flow per page and stalled the UI on ~150-turn sessions. Now the flow window is only extended **on demand**: clicking a capsule for a turn already in the window scrolls directly; for a turn outside the window, the rail extends the window page by page (respecting the paging button's in-flight state) until the target turn is in the window, then scrolls and highlights it.
+- **Immediate jump feedback**: clicking an out-of-window capsule now shows instant feedback — the clicked capsule pulses and a "Locating turn N…" bubble appears beside it (in the DSH tooltip visual style) for the whole duration of the on-demand window extension; on failure a brief "Could not locate turn N" notice shows instead. No more silent waits.
+- **Oldest-turn jumps load to the true start**: jumping to the oldest turn now extends the window until there is no more history to load (hasMore false) — previously the window could include the target's boundary while earlier events were still pending, so the jump landed before the true first turn with a "Load earlier" button remaining. Readiness is judged by the target row being actually rendered in the DOM, not just the turn being listed in the window.
+- **Bilingual README switch**: README (English default) and README.zh.md now link to each other.
+- **Layer stacking**: the rail's z-index is now 10 — above the conversation flow content (max 8) but below full-screen overlays like the kanban board plugin (z-index 50) — matching the header's "Session log" button tier, so an open full-screen page always paints over the rail.
+- **README screenshot**: added `docs/turn-nav-rail.png` to the bilingual README (English default) as marketing, shipped in the npm package.
+
 ## [0.1.0] - 2026-08-19
 
 ### Added

package/README.md

@@ -1,7 +1,11 @@
 # dsh-turn-navigator
 
+**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.
 
+![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:
@@ -9,7 +13,7 @@ In the default DSH web UI, finding a specific turn in a long conversation means
 - 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.
-- **Older history auto-loads**: the conversation paginates its window; the plugin keeps loading earlier pages so every turn is reachable, with no manual "Load earlier" clicks.
+- **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.
 
 ## Installation
 
@@ -28,8 +32,8 @@ dsh web
 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 (the target row briefly highlights); the activated capsule scrolls to the center of the rail unless it is the first or last turn.
-5. Older history loads automatically — the rail fills its visible height first, and scrolling the rail to its top keeps loading earlier turns. No manual "Load earlier" clicks needed.
+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.
 
 ## How it works
 
@@ -41,14 +45,15 @@ The plugin registers **one additive slot** — **no DSH source code is modified*
 
 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).
 
-- **Turn extraction**: `chat.timeline.turnOrder` + `turns` map for boundaries; `chat.locations.getTurn(turn)` for each turn's node keys; the first `kind === 'user'` node's first text block for the summary; `turnTimings` for the timestamp. Turns without a user message fall back to their first node's kind.
+- **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.
-- **Auto-load (stall-free)**: the conversation paginates its history — each page prepend re-renders the whole flow, so loading everything at once would stall the UI. The rail instead (a) slowly fills its visible height after open (slow cadence, back-pressure, page cap), then (b) keeps loading earlier turns while the rail is scrolled near its top — scroll-driven, the same way the conversation itself loads. Clicking a capsule also loads on demand to reach its turn. A shared busy-lock prevents the auto-load and scroll-load paths from ever clicking the paging button concurrently.
+- **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.
 
 ## 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.
 
 ## License
 

package/README.zh.md

@@ -1,7 +1,11 @@
 # dsh-turn-navigator
 
+**[English](README.md) · 简体中文**
+
 一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 外部插件，为会话界面增加**钢琴键式轮次胶囊条**——在会话界面右侧悬浮一条竖向胶囊列，每轮一个小胶囊，让你一眼纵览整场会话有哪几轮，悬停预览，点击跳转到任意轮次起始点。
 
+![轮次导航胶囊条](docs/turn-nav-rail.png)
+
 ## 为什么需要
 
 DSH Web UI 中，在长会话里找某一轮只能靠滚动——没有轮次概览，不知道有几轮、每轮说了什么、当前滚到哪里。`dsh-turn-navigator` 用类似 minimap 的胶囊条解决这个问题：
@@ -9,7 +13,7 @@ DSH Web UI 中，在长会话里找某一轮只能靠滚动——没有轮次概
 - 会话界面右侧**悬浮一条竖向胶囊列**（每轮一个灰色小胶囊，约 3px 高，钢琴键式）。
 - **悬停**某个胶囊：该胶囊以**主题色**亮起并加宽 150%，相邻两个胶囊也稍微加宽（125%）——鼠标滑过时像波浪一样起伏；同时以 DSH 原生 Tooltip 完整展示该轮信息（序号、时间戳、用户消息摘要）。
 - **点击**某个胶囊：会话滚动到该轮起点并短暂高亮。
-- **历史自动加载**：会话历史是分页的，插件自动持续加载更早的页面，直到全部轮次可定位，无需手动点击"加载更早"。
+- **全部轮次即时展示为数据**：胶囊条通过 host 的 `sessions.history` RPC 直接读取完整会话历史（轻量数据，**不 prepend 进会话流**）——即使 150 轮的会话，打开也不重渲染会话流。点击窗口外的轮次时才按需扩展窗口。
 
 ## 安装
 
@@ -28,8 +32,8 @@ dsh web
 1. 打开任意有至少一轮完成的会话。
 2. 会话界面右侧出现一条竖向灰色胶囊列（每轮一个胶囊）。胶囊条**长度自适应**：随轮次多少自动增减，**上限 30vh**——轮次少时胶囊条短，轮次多时达到上限后内部滚动；滚动条隐藏（避免抖动）。上下各有一个**滚动按钮**：支持点击和**悬停持续自动滚动**，没有可滚动内容时自动置灰——轮次再多也不会超出浏览器范围。
 3. 悬停某个胶囊：胶囊**以主题色亮起并向左加宽 150%**（右对齐，右缘不动；相邻两个胶囊也稍微加宽——滑过时形成波浪波纹），胶囊条左侧弹出 DSH 风格 Tooltip，**垂直居中于悬停的胶囊**、始终完整在视口内，展示完整信息（序号、时间戳、用户消息摘要）。
-4. 点击某个胶囊：会话滚动到该轮起点（目标行短暂高亮），**该胶囊自动滚动到胶囊条中央**（首尾两条除外）。
-5. 更早的历史会自动加载——胶囊条先填充自身可视高度，**滚动胶囊条到顶部继续加载更早轮次**。无需手动点击"加载更早"。
+4. 点击某个胶囊：会话滚动到该轮起点（目标行短暂高亮），**该胶囊自动滚动到胶囊条中央**（首尾两条除外）。若目标轮在会话窗口之外，胶囊条会**立即给出反馈**——被点击的胶囊脉冲闪烁，胶囊条左侧弹出"正在定位第 N 轮…"气泡——按需扩展窗口；目标轮进入窗口后滚动定位并高亮。
+5. 所有轮次即时可见（从历史以数据形式读取，不加载会话流）；点击窗口外的轮次时，只加载到达那一轮所需的历史。
 
 ## 原理
 
@@ -41,14 +45,15 @@ dsh web
 
 因为胶囊条是 session 作用域，它直接从框架 `useSession` kit 读取实时 `ConversationSnapshot`，并以 `position: fixed` 渲染（不占据 header 的 flex 行）。
 
-- **轮次提取**：`chat.timeline.turnOrder` + `turns` map 得到轮次边界；`chat.locations.getTurn(turn)` 取该轮 node keys；首个 `kind === 'user'` 节点的首个 text block 作摘要；`turnTimings` 取时间戳。无用户消息的轮次降级显示其首个节点的 kind。
+- **轮次提取**：胶囊条的完整轮次列表来自 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 都会重渲染整个会话流，一次性全加载会卡住界面。胶囊条改为：(a) 打开后以缓慢节奏（背压 + 页数上限）先填充自身可视高度；(b) 之后**滚动胶囊条到顶部时继续加载更早轮次**（滚动驱动，与会话自身加载方式一致）。点击胶囊跳转时也会按需加载到目标轮。自动加载与滚动加载通过共享 busy 锁互斥，绝不并发点击分页按钮。
+- **历史即数据（打开零 prepend）**：会话窗口只把一页事件物化为 DOM，扩展窗口（`loadOlder`）会重渲染整个会话流——长会话代价高。胶囊条改为通过 browser→host 的 `sessions.history` RPC 分页读取完整持久化历史，把每轮派生为纯数据，**打开会话完全不触碰会话流 DOM**。**按需加载**：点击窗口内轮次直接滚动；点击窗口外轮次时，胶囊条逐页扩展窗口（点击"加载更早"分页按钮，尊重其加载中状态）直到目标轮进入窗口，再滚动并高亮——这是唯一会 prepend 会话流的路径，且只在用户点击时发生。
 
 ## 兼容性
 
 - DeepSeek Harness (dsh) Web 客户端（`dsh web`）。
 - 需要 `conversation.session.header.utilities` slot 声明（当前 DSH 已包含）。
+- 与全屏插件页面（如看板）共存：胶囊条层级位于全屏 overlay 之下，打开全屏页面时会覆盖胶囊条。
 
 ## 许可证
 

package/lib/client.js

@@ -9,12 +9,12 @@ window.__ModuleLoader__.load({
 		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 		let react_jsx_runtime = require("react/jsx-runtime");
 		//#region src/client/turns.ts
-		const SUMMARY_MAX_CHARS = 80;
+		const SUMMARY_MAX_CHARS$1 = 80;
 		/**
 		* Extract the text of the first `type: 'text'` content block from a node's
 		* content array.
 		*/
-		function firstText(content) {
+		function firstText$1(content) {
 			if (content === void 0) return "";
 			for (const block of content) if (block.type === "text" && typeof block.text === "string") return block.text;
 			return "";
@@ -52,15 +52,15 @@ window.__ModuleLoader__.load({
 					if (node.kind === "user") {
 						const userData = node.data;
 						if (userData !== void 0) {
-							fullText = firstText(userData.content);
-							summary = fullText.length > SUMMARY_MAX_CHARS ? `${fullText.slice(0, 79)}…` : fullText;
+							fullText = firstText$1(userData.content);
+							summary = fullText.length > SUMMARY_MAX_CHARS$1 ? `${fullText.slice(0, 79)}…` : fullText;
 						}
 						break;
 					}
 					if (summary === "") {
 						const peek = peekNodeText(node);
 						fullText = peek;
-						summary = peek.length > SUMMARY_MAX_CHARS ? `${peek.slice(0, 79)}…` : peek;
+						summary = peek.length > SUMMARY_MAX_CHARS$1 ? `${peek.slice(0, 79)}…` : peek;
 					}
 				}
 				entries.push({
@@ -113,24 +113,123 @@ window.__ModuleLoader__.load({
 			return snap.chat.locations.getTurn(turn)[0];
 		}
 		//#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;
+		function firstText(content) {
+			if (content === void 0) return "";
+			for (const block of content) if (block.type === "text" && typeof block.text === "string") return block.text;
+			return "";
+		}
+		function truncate(text) {
+			return text.length > SUMMARY_MAX_CHARS ? `${text.slice(0, 79)}…` : text;
+		}
+		/**
+		* Read the full persisted history of a session and derive every turn.
+		*
+		* Pages are requested newest-first (a page walks back via `beforeSeq`); all
+		* events are collected, sorted by seq ascending, then folded into turns.
+		* `onPage` is called after each page with the turns derived so far (the rail
+		* can render incrementally without waiting for the whole history).
+		*
+		* @param api - the browser→host sessions API.
+		* @param sessionId - the session to read.
+		* @param onPage - incremental callback (turns so far, in ascending turn order).
+		*/
+		async function fetchAllTurns(api, sessionId, onPage) {
+			const allEvents = [];
+			let beforeSeq;
+			for (let page = 0; page < MAX_HISTORY_PAGES; page += 1) {
+				const response = await api.sessions.history({
+					sessionId,
+					beforeSeq,
+					maxMessages: 50
+				});
+				if (response.result === void 0 || response.result.ok !== true) break;
+				const value = response.result.value;
+				if (value === void 0) break;
+				const { events, hasMore } = value;
+				if (events.length === 0) break;
+				for (const entry of events) allEvents.push(entry.event);
+				onPage(buildTurns(allEvents));
+				if (!hasMore) break;
+				beforeSeq = events[0].event.seq;
+			}
+			allEvents.sort((a, b) => a.seq - b.seq);
+			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);
+			const turns = [];
+			let current = null;
+			for (const event of sorted) switch (event.type) {
+				case "turn/start": {
+					if (current !== null) turns.push(closeTurn(current));
+					const turn = typeof event.data.turn === "number" ? event.data.turn : NaN;
+					if (Number.isFinite(turn)) current = {
+						turn,
+						startSeq: event.seq,
+						time: event.time,
+						summary: "",
+						fullText: ""
+					};
+					break;
+				}
+				case "turn/end":
+					if (current !== null && event.data.turn === current.turn) {
+						turns.push(closeTurn(current));
+						current = null;
+					}
+					break;
+				case "user/message": if (current !== null && current.summary === "") {
+					const text = firstText(event.data.content);
+					current.summary = truncate(text);
+					current.fullText = text;
+					current.time = event.time;
+				}
+			}
+			if (current !== null) turns.push(closeTurn(current));
+			turns.sort((a, b) => a.turn - b.turn);
+			return turns.map((turn, i) => ({
+				...turn,
+				index: i + 1
+			}));
+		}
+		function closeTurn(t) {
+			return {
+				turn: t.turn,
+				index: 0,
+				summary: t.summary || "(no user message)",
+				fullText: t.fullText,
+				startTime: Number.isFinite(t.time) ? t.time : void 0,
+				startSeq: t.startSeq,
+				status: "closed"
+			};
+		}
+		//#endregion
 		//#region src/client/TurnNavRail.tsx
 		/**
 		* Turn navigation rail: a vertical "piano-key" rail floating on the right
-		* edge of the conversation. One capsule per turn (grey, ~3px tall), stacked
-		* vertically. Hovering a capsule makes it glow white and grow (with the two
-		* neighbours slightly raised — a wave ripple), and shows the full turn info
-		* in a DSH Tooltip. Clicking a capsule jumps the conversation to that turn's
-		* start.
+		* edge of the conversation. One capsule per turn, stacked vertically.
+		* Hovering a capsule makes it glow with the theme color and widen (a wave
+		* ripple) and shows the full turn info in a tooltip; clicking a capsule jumps
+		* the conversation to that turn's start.
 		*
 		* Registered into `conversation.session.header.utilities` (session scope), so
-		* this component reads the live `ConversationSnapshot` directly via
-		* `useSession` — no cross-scope bridge needed.
+		* this component reads the live `ConversationSnapshot` via `useSession`.
 		*
-		* Also drives "auto-load older history": the conversation paginates its
-		* window (a "Load earlier" button appears at the top when `hasMore`); this
-		* rail keeps clicking it until all history is loaded, so every turn is
-		* reachable. The same load-and-retry loop backs click-to-jump when the target
-		* row is not yet rendered.
+		* DATA & PERFORMANCE: the rail's turn list is read from the HOST through the
+		* `sessions.history` browser→host RPC — every persisted turn (including ones
+		* far outside the conversation's window) is shown as plain data, with ZERO
+		* prepends into the conversation flow. The flow window is only extended
+		* (via the "Load earlier" paging button) on demand, when a capsule is
+		* clicked to jump to a turn that is not yet in the window. This keeps a very
+		* long conversation (hundreds of turns) responsive: opening it never re-
+		* renders the flow, and jumping loads only what is needed to reach the target.
 		*/
 		/** Scrollport selector: the active conversation's scroll container. */
 		const SCROLL_SELECTOR = "[data-conversation-scroll]";
@@ -138,22 +237,13 @@ window.__ModuleLoader__.load({
 		const ANCHOR_ATTR = "data-chat-anchor-key";
 		/** CSS class for the jump highlight flash. */
 		const HIGHLIGHT_CLASS = "tn-jump-highlight";
-		/** Loaded-but-not-found retry window for click-to-jump (ms). */
-		const JUMP_TIMEOUT_MS = 5e3;
-		/** Delay between auto-load button clicks — lets the conversation render the
-		*  prepended page (a heavy full-flow re-render) before the next one. */
-		const LOAD_RENDER_SETTLE_MS = 700;
-		/** Cap on pages auto-loaded per session open. Loading the entire history of a
-		*  very long conversation at once would stall the UI; the rail fills up
-		*  first (visual cap) and the rest is loaded on-demand. */
-		const MAX_AUTO_PAGES = 30;
-		/** Cap on pages loaded while hunting a specific turn's row (click-to-jump). */
-		const MAX_JUMP_PAGES = 40;
+		/** Delay between loadOlder clicks while expanding the window to a clicked turn. */
+		const LOAD_RENDER_SETTLE_MS = 900;
+		/** Cap on pages loaded while expanding the window to a clicked turn. */
+		const MAX_JUMP_PAGES = 100;
 		/** 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 (the
-		*  conversation swaps the label to a "loading…" copy while a page is being
-		*  fetched; we must still recognize the button so loading state is tracked). */
+		/** Localized "Load earlier" paging button labels — idle AND in-flight. */
 		const LOAD_OLDER_TEXTS = /* @__PURE__ */ new Set([
 			"加载更早",
 			"Load earlier",
@@ -171,11 +261,7 @@ window.__ModuleLoader__.load({
 		function findScrollport() {
 			return document.querySelector(SCROLL_SELECTOR) ?? void 0;
 		}
-		/**
-		* Find the "Load earlier" paging button inside the conversation flow, or null
-		* when all history is already loaded (button absent) / currently loading
-		* (button disabled).
-		*/
+		/** Find the "Load earlier" paging button, or null (absent / mid-flight). */
 		function findLoadOlderButton() {
 			const scrollport = findScrollport();
 			if (scrollport === void 0) return null;
@@ -183,57 +269,20 @@ window.__ModuleLoader__.load({
 			for (const btn of candidates) if (isLoadOlderButton(btn)) return btn;
 			return null;
 		}
-		/**
-		* Wait for a chat row with the given node key to appear in the DOM, driving
-		* the "load earlier" button meanwhile (the target turn may live in a not-yet
-		* loaded page). Resolves with the row, or null on timeout / page cap.
-		*/
-		function waitForRow(scrollport, key, timeoutMs) {
+		/** Promise-based sleep. */
+		function sleep(ms) {
 			return new Promise((resolve) => {
-				const deadline = Date.now() + timeoutMs;
-				let pages = 0;
-				const check = () => {
-					const row = scrollport.querySelector(`[${ANCHOR_ATTR}="${CSS.escape(key)}"]`);
-					if (row !== null) {
-						resolve(row);
-						return;
-					}
-					if (Date.now() > deadline || pages >= MAX_JUMP_PAGES) {
-						resolve(null);
-						return;
-					}
-					const btn = findLoadOlderButton();
-					if (btn !== null && !btn.disabled) {
-						btn.click();
-						pages += 1;
-					}
-					setTimeout(check, 150);
-				};
-				check();
+				setTimeout(resolve, ms);
 			});
 		}
-		/**
-		* Jump to a turn: locate its first chat-node row (auto-loading earlier
-		* history until it renders) and scroll the conversation flow to it, with a
-		* brief highlight flash.
-		*/
-		async function jumpToTurn(snapshot, turn) {
-			if (snapshot === void 0) return;
-			const key = firstNodeKeyOfTurn(snapshot, turn);
-			if (key === void 0) return;
-			const scrollport = findScrollport();
-			if (scrollport === void 0) return;
-			const row = await waitForRow(scrollport, key, JUMP_TIMEOUT_MS);
-			if (row === null) return;
-			const targetTop = row.getBoundingClientRect().top - scrollport.getBoundingClientRect().top + scrollport.scrollTop;
-			scrollport.scrollTop = Math.max(0, targetTop - JUMP_MARGIN_PX);
-			row.classList.add(HIGHLIGHT_CLASS);
-			setTimeout(() => row.classList.remove(HIGHLIGHT_CLASS), 1500);
+		/** Keep the jump-feedback bubble inside the viewport vertically. */
+		function clampFeedbackY(y) {
+			return Math.max(24, Math.min(y, window.innerHeight - 24));
 		}
 		/** Tooltip body for one turn: index, time, full summary. */
-		function tooltipText(entry, index, t) {
+		function tooltipText(entry, t) {
 			const time = formatTime(entry.startTime);
-			const label = t("turnLabel", { n: String(index) });
+			const label = t("turnLabel", { n: String(entry.index) });
 			const body = entry.fullText || entry.summary || t("noSummary");
 			const lines = [label];
 			if (time !== "") lines.push(time);
@@ -248,81 +297,42 @@ window.__ModuleLoader__.load({
 		}
 		/**
 		* The piano-key rail. Session scope: reads the conversation snapshot directly
-		* and renders a floating vertical capsule per turn.
+		* 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, t }) {
+		function TurnNavRail({ useSession, sessionId, t, api }) {
 			const snapshot = useSession?.((s) => s);
-			const turns = (0, react.useMemo)(() => extractTurns(snapshot), [snapshot]);
+			const snapshotRef = (0, react.useRef)(snapshot);
+			snapshotRef.current = snapshot;
+			const windowTurns = (0, react.useMemo)(() => extractTurns(snapshot), [snapshot]);
+			const [historyTurns, setHistoryTurns] = (0, react.useState)([]);
 			const [hoverIndex, setHoverIndex] = (0, react.useState)(-1);
 			const [hoverY, setHoverY] = (0, react.useState)(0);
 			const [tipTop, setTipTop] = (0, react.useState)(0);
 			const [canScrollUp, setCanScrollUp] = (0, react.useState)(false);
 			const [canScrollDown, setCanScrollDown] = (0, react.useState)(false);
-			const autoPagesRef = (0, react.useRef)(0);
-			const loadBusyRef = (0, react.useRef)(false);
+			const [jumpState, setJumpState] = (0, react.useState)(null);
 			const railRef = (0, react.useRef)(null);
 			const tipRef = (0, react.useRef)(null);
 			const hoverScrollRef = (0, react.useRef)(null);
-			const loadMoreOnce = (0, react.useCallback)((then) => {
-				if (loadBusyRef.current) {
-					then(false);
-					return;
-				}
-				const btn = findLoadOlderButton();
-				if (btn === null || btn.disabled) {
-					then(false);
-					return;
-				}
-				loadBusyRef.current = true;
-				btn.click();
-				setTimeout(() => {
-					loadBusyRef.current = false;
-					then(true);
-				}, LOAD_RENDER_SETTLE_MS);
-			}, []);
-			const hasTurns = turns.length > 0;
 			(0, react.useEffect)(() => {
-				if (!hasTurns) return;
-				autoPagesRef.current = 0;
-				let timer = null;
-				let stopped = false;
-				const tick = () => {
-					if (stopped || autoPagesRef.current >= MAX_AUTO_PAGES) return;
-					const rail = railRef.current;
-					if (rail !== null && rail.scrollHeight > rail.clientHeight + 2) return;
-					if (findLoadOlderButton() === null) return;
-					loadMoreOnce((loaded) => {
-						if (loaded) autoPagesRef.current += 1;
-						if (!stopped) timer = setTimeout(tick, 300);
-					});
-				};
-				timer = setTimeout(tick, 300);
+				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);
+				});
 				return () => {
-					stopped = true;
-					if (timer !== null) clearTimeout(timer);
+					cancelled = true;
 				};
-			}, [hasTurns, loadMoreOnce]);
-			(0, react.useEffect)(() => {
-				const rail = railRef.current;
-				if (rail === null) return;
-				const onScroll = () => {
-					if (rail.scrollTop > 60) return;
-					const btn = findLoadOlderButton();
-					if (btn === null) return;
-					if (loadBusyRef.current || btn.disabled) {
-						setTimeout(onScroll, 150);
-						return;
-					}
-					loadBusyRef.current = true;
-					btn.click();
-					setTimeout(() => {
-						loadBusyRef.current = false;
-						if (rail.scrollTop <= 60) setTimeout(onScroll, 150);
-					}, LOAD_RENDER_SETTLE_MS);
-				};
-				rail.addEventListener("scroll", onScroll, { passive: true });
-				return () => rail.removeEventListener("scroll", onScroll);
-			}, [hasTurns]);
+			}, [api, sessionId]);
+			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]);
 			(0, react.useEffect)(() => {
 				const rail = railRef.current;
 				if (rail === null) return;
@@ -384,6 +394,64 @@ window.__ModuleLoader__.load({
 				const target = btnRect.top - contentTop - (rail.clientHeight - btnRect.height) / 2;
 				rail.scrollTop = Math.max(0, target);
 			};
+			const jumpToTurn = async (turn) => {
+				const scrollport = findScrollport();
+				if (scrollport === void 0) return false;
+				const isOldest = turns[0]?.turn === turn;
+				const scrollToRow = (row) => {
+					const targetTop = row.getBoundingClientRect().top - scrollport.getBoundingClientRect().top + scrollport.scrollTop;
+					scrollport.scrollTop = Math.max(0, targetTop - JUMP_MARGIN_PX);
+					row.classList.add(HIGHLIGHT_CLASS);
+					setTimeout(() => row.classList.remove(HIGHLIGHT_CLASS), 1500);
+				};
+				for (let i = 0; i < MAX_JUMP_PAGES; i += 1) {
+					const snap = snapshotRef.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);
+							return true;
+						}
+					}
+					const btn = findLoadOlderButton();
+					if (btn === null) {
+						if (row !== null) {
+							scrollToRow(row);
+							return true;
+						}
+						return false;
+					}
+					if (btn.disabled) {
+						await sleep(150);
+						continue;
+					}
+					btn.click();
+					await sleep(LOAD_RENDER_SETTLE_MS);
+				}
+				return false;
+			};
+			const handleCapsuleClick = (turn, index, e) => {
+				centerCapsule(index);
+				const y = e.currentTarget.getBoundingClientRect().top + e.currentTarget.getBoundingClientRect().height / 2;
+				setJumpState({
+					turn,
+					y,
+					phase: "loading"
+				});
+				jumpToTurn(turn).then((ok) => {
+					if (ok) setJumpState(null);
+					else {
+						setJumpState({
+							turn,
+							y,
+							phase: "error"
+						});
+						setTimeout(() => setJumpState(null), 2500);
+					}
+				});
+			};
 			if (turns.length === 0) return null;
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "tn-wrap",
@@ -411,19 +479,18 @@ window.__ModuleLoader__.load({
 						className: "tn-rail",
 						children: turns.map((entry, i) => {
 							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;
 							return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								type: "button",
-								className: `tn-cap-btn${dist === 0 ? " tn-cap-hot" : dist === 1 ? " tn-cap-warm" : ""}`,
+								className: `tn-cap-btn${cls}${loading ? " tn-loading" : ""}`,
 								onMouseEnter: (e) => {
 									setHoverIndex(i);
 									const rect = e.currentTarget.getBoundingClientRect();
 									setHoverY(rect.top + rect.height / 2);
 								},
-								onClick: () => {
-									jumpToTurn(snapshot, entry.turn);
-									centerCapsule(i);
-								},
-								"aria-label": tooltipText(entry, entry.index, t).replace(/\n/g, " — "),
+								onClick: (e) => handleCapsuleClick(entry.turn, i, e),
+								"aria-label": tooltipText(entry, t).replace(/\n/g, " — "),
 								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { className: "tn-cap" })
 							}, entry.turn);
 						})
@@ -440,12 +507,19 @@ window.__ModuleLoader__.load({
 						onMouseLeave: stopHoverScroll,
 						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutline14, { size: 12 })
 					}),
+					jumpState !== null && (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: `tn-jump-feedback${jumpState.phase === "error" ? " tn-jump-error" : ""}`,
+						style: { top: clampFeedbackY(jumpState.y) },
+						role: "status",
+						"aria-live": "polite",
+						children: jumpState.phase === "loading" ? t("locatingTurn", { n: String(jumpState.turn) }) : t("locateFailed", { n: String(jumpState.turn) })
+					}), document.body),
 					hoverEntry !== void 0 && (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 						ref: tipRef,
 						className: "tn-tip",
 						style: { top: tipTop },
 						role: "tooltip",
-						children: tooltipText(hoverEntry, hoverEntry.index, t)
+						children: tooltipText(hoverEntry, t)
 					}), document.body)
 				]
 			});
@@ -466,13 +540,17 @@ window.__ModuleLoader__.load({
 		const en = {
 			rail: "Turn navigation",
 			turnLabel: "Turn {n}",
-			noSummary: "(no user message)"
+			noSummary: "(no user message)",
+			locatingTurn: "Locating turn {n}…",
+			locateFailed: "Could not locate turn {n}"
 		};
 		/** Chinese strings (same keys as {@link en}). */
 		const zh = {
 			rail: "轮次导航",
 			turnLabel: "第 {n} 轮",
-			noSummary: "（无用户消息）"
+			noSummary: "（无用户消息）",
+			locatingTurn: "正在定位第 {n} 轮…",
+			locateFailed: "无法定位第 {n} 轮"
 		};
 		//#endregion
 		//#region src/client/styles.ts
@@ -489,7 +567,11 @@ window.__ModuleLoader__.load({
 		const TURN_NAV_STYLES = `
 /* Wrapper: fixed column on the right edge (scroll buttons + rail + tooltip).
    The whole wrapper is pointer-events:auto so the wheel scrolls the rail
-   anywhere on it; buttons sit above and below the rail. */
+   anywhere on it; buttons sit above and below the rail.
+   z-index is deliberately LOW (10): above the conversation flow content
+   (max 8) but below full-screen overlays like the kanban board plugin
+   (z-index 50) — same order of magnitude as the header's "Session log"
+   button, so an open full-screen page always paints over the rail. */
 .tn-wrap {
   position: fixed;
   right: 6px;
@@ -498,7 +580,7 @@ window.__ModuleLoader__.load({
   display: flex;
   flex-direction: column;
   align-items: center;
-  z-index: 30;
+  z-index: 10;
   pointer-events: auto;
 }
 /* Up/down scroll controls at the top and bottom of the rail. Disabled (grey,
@@ -615,6 +697,53 @@ window.__ModuleLoader__.load({
   from { opacity: 0; }
 }
 
+/* On-demand jump feedback: a bubble to the LEFT of the rail showing that a
+   turn is being located (loading, with a pulsing dot) or that locating
+   failed. Mirrors the tooltip visual but with a status dot. */
+.tn-jump-feedback {
+  position: fixed;
+  right: 40px;
+  transform: translateY(-50%);
+  z-index: 101;
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  padding: 5px 10px;
+  border-radius: 8px;
+  background: var(--dsw-alias-tooltip-bg);
+  color: var(--dsw-static-neutral-bluish-00);
+  font-size: 12px;
+  line-height: 18px;
+  white-space: nowrap;
+  max-width: 45vw;
+  pointer-events: none;
+  animation: tn-tooltip-in 150ms var(--ds-ease-in-out);
+}
+.tn-jump-feedback::before {
+  content: '';
+  flex: none;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: currentColor;
+  animation: tn-loading-pulse 1s ease-in-out infinite;
+}
+.tn-jump-feedback.tn-jump-error {
+  color: var(--dsw-alias-state-error-primary);
+}
+.tn-jump-feedback.tn-jump-error::before {
+  background: var(--dsw-alias-state-error-primary);
+  animation: none;
+}
+/* The clicked capsule pulses while its turn is being located. */
+.tn-cap-btn.tn-loading .tn-cap {
+  animation: tn-loading-pulse 900ms ease-in-out infinite;
+}
+@keyframes tn-loading-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.25; }
+}
+
 /* Jump highlight flash on the target row in the conversation flow. */
 @keyframes tn-highlight-flash {
   0% { background: color-mix(in srgb, var(--dsw-alias-brand-primary) 26%, transparent); }
@@ -645,7 +774,11 @@ window.__ModuleLoader__.load({
 		/** Dictionary namespace owned by this plugin. */
 		const NS = "dsh-turn-navigator";
 		/** Required services (cordis fiber inject). */
-		const inject = ["slots", "locale"];
+		const inject = [
+			"slots",
+			"locale",
+			"connection"
+		];
 		/**
 		* Browser plugin body: registers the turn rail into the session header
 		* utilities seat.
@@ -657,12 +790,16 @@ window.__ModuleLoader__.load({
 				en
 			}), "dsh-turn-navigator: copy dictionaries");
 			const t = ctx.locale.bind(NS);
+			const api = ctx.get("connection")?.api;
 			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 })
+				inject: () => ({
+					t,
+					api
+				})
 			}, TurnNavRail));
 		}
 		//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-turn-navigator",
-  "version": "0.1.0",
+  "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.",
   "type": "module",
   "main": "lib/index.js",
@@ -17,6 +17,7 @@
     "lib/index.js",
     "lib/client.js",
     "cordis.patch.yml",
+    "docs/turn-nav-rail.png",
     "README.md",
     "README.zh.md",
     "CHANGELOG.md",