dsh-turn-navigator 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [0.1.0] - 2026-08-19
+
+### Added
+
+- Initial release: piano-key turn navigation rail for DSH web conversations.
+- A vertical rail of grey capsules floats on the right edge of the conversation — one capsule per turn (registered into `conversation.session.header.utilities`; `position: fixed`).
+- The rail is **height-capped (60vh) and scrolls internally**, so a very long conversation never pushes it past the viewport.
+- Wave hover: hovering a capsule makes it glow with the **theme's primary label color** and widen to 150% (the two neighbours widen to 125%), sliding across the rail like a wave. Widening uses transform:scaleX, so it never reflows or adds a horizontal scrollbar.
+- Native DSH tooltip on hover showing the turn's index, timestamp, and user-message summary (multi-line, `\n`-separated).
+- Click-to-jump: scrolls the conversation flow to the turn's first node and briefly highlights it — computed via the scrollport's `scrollTop` and the `data-chat-anchor-key` DOM anchor.
+- **Stall-free auto-load**: the rail slowly fills its visible height after open (slow cadence, back-pressure, page cap), then keeps loading earlier turns while scrolled near its top — scroll-driven, like the conversation itself. A shared busy-lock prevents concurrent paging clicks.
+- **Custom tooltip bubble** (DSH visual style, multi-line) anchored to the **left** of the rail — rendered via a React portal to `document.body` so it stays viewport-fixed (a transform on the wrapper would otherwise misplace it), vertically centered on the hovered capsule, and clamped so the whole bubble stays inside the viewport even when the summary is long.
+- **Auto-sizing rail**: its length grows with the turn count, capped at **30vh**; scrolls internally (hidden scrollbar) once the cap is hit.
+- **Up/down scroll buttons**: click to scroll ~1 viewport-height, and **hover-hold auto-scrolls** continuously; each is greyed out (disabled) when there is nothing to scroll in that direction.
+- **Center-on-activate**: clicking a capsule scrolls it to the center of the rail, unless it is the first or last turn (which sit at the edges).
+- Wave widening is **right-origin** (`transform-origin: right`), so capsules grow LEFTWARD only — the right edge never moves.
+- Jump retry: if a target turn's row is not yet rendered (older page not loaded), the jump auto-clicks "Load earlier" (recognizing the idle and in-flight labels) and retries until the row appears — no "scroll once first" friction.
+- Bilingual README (en/zh), CHANGELOG, CONTRIBUTING, LICENSE, release-check + post-publish-check scripts, Playwright rail verification script.
+
+### Changed
+
+- Replaced the earlier drawer-based design (header trigger pill + `shell.overlay` drawer + module-level relay bridge) with the single session-scoped rail, which reads `useSession` directly — simpler and one additive slot instead of two.
+- Wave hover changed from height growth to **width widening** via transform:scaleX (150% / 125%) — no reflow, no horizontal scrollbar, no layout drift while sliding. Rail is now pointer-events:auto (wheel scrolls anywhere on it, including the gaps) with overflow-x:hidden. Hover color follows the theme (primary label token).

package/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+## Development workflow
+
+```sh
+pnpm install
+pnpm typecheck      # tsc --noEmit
+pnpm bundle         # tsdown build → lib/index.js + lib/client.js
+```
+
+## Release workflow
+
+Every release must be done in one pass: code + bilingual README + CHANGELOG + version + tag.
+
+1. Make your changes.
+2. Update `README.md`, `README.zh.md` (same `##`/`###` section counts), and `CHANGELOG.md`.
+3. Bump `package.json` version.
+4. `git commit && git tag v<version> && git push --tags`.
+5. `pnpm release:check` — verifies version, docs, changelog, tag, tree, build, registry.
+6. `npm pack --dry-run` — confirm tarball contents.
+7. `npm publish` (requires 2FA; the agent cannot do this step).
+8. `postpublish` runs `scripts/post-publish-check.mjs` automatically.
+
+## npm publish is manual (2FA)
+
+npm accounts with two-factor authentication require an OTP that the agent cannot provide. The agent prepares everything to "one command to publish"; the human runs `npm login` → `npm publish`.
+
+## Post-release release-check "failures" are expected
+
+After a version is published, `release:check` will fail because the version is already on npm and the tag no longer points at HEAD. This is by design — it protects already-published versions. Bump the version and tag a new release instead.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 karoc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# dsh-turn-navigator
+
+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.
+
+## 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.
+- **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.
+
+## Installation
+
+```sh
+dsh plugin --profile web add dsh-turn-navigator
+```
+
+Then restart `dsh web`:
+
+```sh
+dsh web
+```
+
+## Usage
+
+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.
+
+## How it works
+
+The plugin registers **one additive slot** — **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).
+
+- **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.
+- **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.
+
+## Compatibility
+
+- DeepSeek Harness (dsh) with the web client (`dsh web`).
+- Requires the `conversation.session.header.utilities` slot declaration (present in current DSH).
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,55 @@
+# dsh-turn-navigator
+
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 外部插件，为会话界面增加**钢琴键式轮次胶囊条**——在会话界面右侧悬浮一条竖向胶囊列，每轮一个小胶囊，让你一眼纵览整场会话有哪几轮，悬停预览，点击跳转到任意轮次起始点。
+
+## 为什么需要
+
+DSH Web UI 中，在长会话里找某一轮只能靠滚动——没有轮次概览，不知道有几轮、每轮说了什么、当前滚到哪里。`dsh-turn-navigator` 用类似 minimap 的胶囊条解决这个问题：
+
+- 会话界面右侧**悬浮一条竖向胶囊列**（每轮一个灰色小胶囊，约 3px 高，钢琴键式）。
+- **悬停**某个胶囊：该胶囊以**主题色**亮起并加宽 150%，相邻两个胶囊也稍微加宽（125%）——鼠标滑过时像波浪一样起伏；同时以 DSH 原生 Tooltip 完整展示该轮信息（序号、时间戳、用户消息摘要）。
+- **点击**某个胶囊：会话滚动到该轮起点并短暂高亮。
+- **历史自动加载**：会话历史是分页的，插件自动持续加载更早的页面，直到全部轮次可定位，无需手动点击"加载更早"。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-turn-navigator
+```
+
+然后重启 `dsh web`：
+
+```sh
+dsh web
+```
+
+## 使用
+
+1. 打开任意有至少一轮完成的会话。
+2. 会话界面右侧出现一条竖向灰色胶囊列（每轮一个胶囊）。胶囊条**长度自适应**：随轮次多少自动增减，**上限 30vh**——轮次少时胶囊条短，轮次多时达到上限后内部滚动；滚动条隐藏（避免抖动）。上下各有一个**滚动按钮**：支持点击和**悬停持续自动滚动**，没有可滚动内容时自动置灰——轮次再多也不会超出浏览器范围。
+3. 悬停某个胶囊：胶囊**以主题色亮起并向左加宽 150%**（右对齐，右缘不动；相邻两个胶囊也稍微加宽——滑过时形成波浪波纹），胶囊条左侧弹出 DSH 风格 Tooltip，**垂直居中于悬停的胶囊**、始终完整在视口内，展示完整信息（序号、时间戳、用户消息摘要）。
+4. 点击某个胶囊：会话滚动到该轮起点（目标行短暂高亮），**该胶囊自动滚动到胶囊条中央**（首尾两条除外）。
+5. 更早的历史会自动加载——胶囊条先填充自身可视高度，**滚动胶囊条到顶部继续加载更早轮次**。无需手动点击"加载更早"。
+
+## 原理
+
+插件只注册**一个加法 slot**——**不修改 DSH 源码**：
+
+| Slot | 作用域 | 职责 |
+|------|--------|------|
+| `conversation.session.header.utilities` | session | 悬浮轮次胶囊条；直接通过 `useSession` 读取 |
+
+因为胶囊条是 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。
+- **跳转定位**：取该轮第一个 chat-node key，通过 `data-chat-anchor-key="<key>"` 找到 DOM 行，在 `[data-conversation-scroll]` 滚动容器中精确计算并设置 `scrollTop`（比 `scrollIntoView` 更可控）。若目标行尚未渲染（更早页面未加载），自动点击"加载更早"按钮并重试直到行出现——无需先滚动一下。
+- **自动加载（不卡顿）**：会话历史是分页的，每页 prepend 都会重渲染整个会话流，一次性全加载会卡住界面。胶囊条改为：(a) 打开后以缓慢节奏（背压 + 页数上限）先填充自身可视高度；(b) 之后**滚动胶囊条到顶部时继续加载更早轮次**（滚动驱动，与会话自身加载方式一致）。点击胶囊跳转时也会按需加载到目标轮。自动加载与滚动加载通过共享 busy 锁互斥，绝不并发点击分页按钮。
+
+## 兼容性
+
+- DeepSeek Harness (dsh) Web 客户端（`dsh web`）。
+- 需要 `conversation.session.header.utilities` slot 声明（当前 DSH 已包含）。
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# Bundle layer applied when a profile lists this package. The row names the
+# package by name so Node resolution finds the installed code; its browser half
+# (exports["./client"] + dsh.client manifest) is discovered by dsh web's
+# client-modules service and served at /plugins/dsh-turn-navigator/client.js.
+# The host half is an empty apply (no tools/routes); the client half registers
+# the session-header trigger and the shell.overlay drawer.
+- insert:
+    - id: dsh-turn-navigator
+      name: dsh-turn-navigator

package/lib/client.js

@@ -0,0 +1,675 @@
+window.__ModuleLoader__.load({
+	id: "dsh-turn-navigator",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		let react_dom = require("react-dom");
+		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;
+		/**
+		* Extract the text of the first `type: 'text'` content block from a node's
+		* content array.
+		*/
+		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 "";
+		}
+		/**
+		* Derive the flat turn list from a conversation 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`.
+		*
+		* @param snap - the conversation 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 timeline = chat.timeline;
+			const turnOrder = timeline.turnOrder;
+			if (turnOrder.length === 0) return [];
+			const entries = [];
+			let displayIndex = 0;
+			for (const turn of turnOrder) {
+				displayIndex += 1;
+				const loc = timeline.turns.get(turn);
+				const status = loc?.status ?? "unknown";
+				const startTime = snap.turnTimings.get(turn)?.startTime ?? loc?.start?.time;
+				let summary = "";
+				let fullText = "";
+				const keys = chat.locations.getTurn(turn);
+				for (const key of keys) {
+					const node = chat.nodes.get(key);
+					if (node === void 0) continue;
+					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;
+						}
+						break;
+					}
+					if (summary === "") {
+						const peek = peekNodeText(node);
+						fullText = peek;
+						summary = peek.length > SUMMARY_MAX_CHARS ? `${peek.slice(0, 79)}…` : peek;
+					}
+				}
+				entries.push({
+					turn,
+					index: displayIndex,
+					summary: summary || `[${kindLabel(turn, keys, chat)}]`,
+					fullText,
+					startTime,
+					status
+				});
+			}
+			return entries;
+		}
+		/** Best-effort text peek from a non-user chat node's data (erased shape). */
+		function peekNodeText(node) {
+			const data = node.data;
+			if (data === void 0) return "";
+			for (const field of [
+				"summary",
+				"text",
+				"content",
+				"message",
+				"name"
+			]) {
+				const value = data[field];
+				if (typeof value === "string" && value.trim().length > 0) return value.trim();
+				if (Array.isArray(value)) {
+					for (const block of value) if (block !== null && typeof block === "object") {
+						const b = block;
+						if (typeof b.text === "string" && b.text.trim().length > 0) return b.text.trim();
+					}
+				}
+			}
+			return "";
+		}
+		/** Human label for a turn that has no readable first-node text. */
+		function kindLabel(turn, keys, chat) {
+			return `turn ${turn} (${chat.nodes.get(keys[0] ?? "")?.kind ?? "turn"})`;
+		}
+		/**
+		* Find the chat-node key of the first visible node in a given turn — the
+		* scroll target for "jump to turn".
+		*
+		* @param snap - the conversation snapshot.
+		* @param turn - the turn number to jump to.
+		* @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];
+		}
+		//#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.
+		*
+		* Registered into `conversation.session.header.utilities` (session scope), so
+		* this component reads the live `ConversationSnapshot` directly via
+		* `useSession` — no cross-scope bridge needed.
+		*
+		* 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.
+		*/
+		/** Scrollport selector: the active conversation's scroll container. */
+		const SCROLL_SELECTOR = "[data-conversation-scroll]";
+		/** Chat row anchor attribute: each rendered row carries its node key. */
+		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;
+		/** 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). */
+		const LOAD_OLDER_TEXTS = /* @__PURE__ */ new Set([
+			"加载更早",
+			"Load earlier",
+			"Load earlier…",
+			"加载中",
+			"加载中…",
+			"Loading",
+			"Loading…"
+		]);
+		function isLoadOlderButton(el) {
+			const text = (el.textContent ?? "").trim();
+			return LOAD_OLDER_TEXTS.has(text);
+		}
+		/** Find the scrollport (the conversation's scroll container). */
+		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).
+		*/
+		function findLoadOlderButton() {
+			const scrollport = findScrollport();
+			if (scrollport === void 0) return null;
+			const candidates = scrollport.querySelectorAll("button");
+			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) {
+			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();
+			});
+		}
+		/**
+		* 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);
+		}
+		/** Tooltip body for one turn: index, time, full summary. */
+		function tooltipText(entry, index, t) {
+			const time = formatTime(entry.startTime);
+			const label = t("turnLabel", { n: String(index) });
+			const body = entry.fullText || entry.summary || t("noSummary");
+			const lines = [label];
+			if (time !== "") lines.push(time);
+			lines.push(body);
+			return lines.join("\n");
+		}
+		/** Short HH:MM from a Unix-epoch-ms timestamp. */
+		function formatTime(ms) {
+			if (ms === void 0 || ms === null || !Number.isFinite(ms)) return "";
+			const date = new Date(ms);
+			return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+		}
+		/**
+		* The piano-key rail. Session scope: reads the conversation snapshot directly
+		* and renders a floating vertical capsule per turn.
+		*/
+		function TurnNavRail({ useSession, t }) {
+			const snapshot = useSession?.((s) => s);
+			const turns = (0, react.useMemo)(() => extractTurns(snapshot), [snapshot]);
+			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 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);
+				return () => {
+					stopped = true;
+					if (timer !== null) clearTimeout(timer);
+				};
+			}, [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]);
+			(0, react.useEffect)(() => {
+				const rail = railRef.current;
+				if (rail === null) return;
+				const update = () => {
+					setCanScrollUp(rail.scrollTop > 2);
+					setCanScrollDown(rail.scrollTop < rail.scrollHeight - rail.clientHeight - 2);
+				};
+				update();
+				rail.addEventListener("scroll", update, { passive: true });
+				const ro = new ResizeObserver(update);
+				ro.observe(rail);
+				return () => {
+					rail.removeEventListener("scroll", update);
+					ro.disconnect();
+				};
+			}, [turns.length]);
+			const hoverEntry = hoverIndex >= 0 ? turns[hoverIndex] : void 0;
+			(0, react.useEffect)(() => {
+				if (hoverEntry === void 0) return;
+				const tip = tipRef.current;
+				if (tip === null) return;
+				const h = tip.offsetHeight;
+				setTipTop(Math.max(8, Math.min(hoverY - h / 2, window.innerHeight - h - 8)));
+			}, [hoverEntry, hoverY]);
+			(0, react.useEffect)(() => () => stopHoverScroll(), []);
+			const startHoverScroll = (dir) => {
+				stopHoverScroll();
+				if (railRef.current === null) return;
+				const step = () => {
+					const r = railRef.current;
+					if (r === null) return;
+					if (dir < 0 && r.scrollTop <= 2) {
+						stopHoverScroll();
+						return;
+					}
+					if (dir > 0 && r.scrollTop >= r.scrollHeight - r.clientHeight - 2) {
+						stopHoverScroll();
+						return;
+					}
+					r.scrollBy({ top: dir * 24 });
+				};
+				step();
+				hoverScrollRef.current = setInterval(step, 120);
+			};
+			function stopHoverScroll() {
+				if (hoverScrollRef.current !== null) {
+					clearInterval(hoverScrollRef.current);
+					hoverScrollRef.current = null;
+				}
+			}
+			const centerCapsule = (index) => {
+				const rail = railRef.current;
+				if (rail === null) return;
+				const btn = rail.querySelectorAll(".tn-cap-btn")[index];
+				if (btn === void 0) return;
+				const railRect = rail.getBoundingClientRect();
+				const btnRect = btn.getBoundingClientRect();
+				const contentTop = railRect.top - rail.scrollTop;
+				const target = btnRect.top - contentTop - (rail.clientHeight - btnRect.height) / 2;
+				rail.scrollTop = Math.max(0, target);
+			};
+			if (turns.length === 0) return null;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "tn-wrap",
+				role: "navigation",
+				"aria-label": t("rail"),
+				onMouseLeave: () => {
+					setHoverIndex(-1);
+					stopHoverScroll();
+				},
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						className: "tn-scroll-btn",
+						"aria-label": "scroll rail up",
+						disabled: !canScrollUp,
+						onClick: () => scrollRail(railRef.current, -1),
+						onMouseEnter: () => {
+							if (canScrollUp) startHoverScroll(-1);
+						},
+						onMouseLeave: stopHoverScroll,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronUpOutline14, { size: 12 })
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						ref: railRef,
+						className: "tn-rail",
+						children: turns.map((entry, i) => {
+							const dist = hoverIndex === -1 ? Infinity : Math.abs(i - hoverIndex);
+							return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: `tn-cap-btn${dist === 0 ? " tn-cap-hot" : dist === 1 ? " tn-cap-warm" : ""}`,
+								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, " — "),
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { className: "tn-cap" })
+							}, entry.turn);
+						})
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						className: "tn-scroll-btn",
+						"aria-label": "scroll rail down",
+						disabled: !canScrollDown,
+						onClick: () => scrollRail(railRef.current, 1),
+						onMouseEnter: () => {
+							if (canScrollDown) startHoverScroll(1);
+						},
+						onMouseLeave: stopHoverScroll,
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutline14, { size: 12 })
+					}),
+					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)
+					}), document.body)
+				]
+			});
+		}
+		/** Scroll the rail by roughly one viewport-height (smooth). */
+		function scrollRail(rail, dir) {
+			if (rail === null) return;
+			const step = Math.max(60, rail.clientHeight * .8);
+			rail.scrollBy({
+				top: dir * step,
+				behavior: "smooth"
+			});
+		}
+		//#endregion
+		//#region src/client/locales.ts
+		/** Copy dictionaries for the dsh-turn-navigator plugin. */
+		/** English strings (the key-set source of truth for this pair). */
+		const en = {
+			rail: "Turn navigation",
+			turnLabel: "Turn {n}",
+			noSummary: "(no user message)"
+		};
+		/** Chinese strings (same keys as {@link en}). */
+		const zh = {
+			rail: "轮次导航",
+			turnLabel: "第 {n} 轮",
+			noSummary: "（无用户消息）"
+		};
+		//#endregion
+		//#region src/client/styles.ts
+		/**
+		* Design-token styles for the turn-nav piano-key rail (external plugin, no
+		* CSS modules available). Re-declared against the official `--dsw-alias-*`
+		* semantic tokens, namespaced under `tn-` to avoid collisions. Tokens carry
+		* no fallback because the host theme always defines them on the app root.
+		*
+		* Wave hover: hovering a capsule makes it glow white and WIDEN (150%);
+		* its two neighbours widen a little too (125%), so sliding across the rail
+		* ripples like a wave (hot = hovered, warm = adjacent). Height stays ~3px.
+		*/
+		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. */
+.tn-wrap {
+  position: fixed;
+  right: 6px;
+  top: 50%;
+  transform: translateY(-50%);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  z-index: 30;
+  pointer-events: auto;
+}
+/* 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. */
+.tn-scroll-btn {
+  flex: none;
+  width: 26px;
+  height: 18px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+.tn-scroll-btn:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-primary);
+}
+.tn-scroll-btn:disabled {
+  color: var(--dsw-alias-label-tertiary);
+  opacity: 0.45;
+  cursor: default;
+}
+/* Rail: AUTO-SIZING vertical column — its length grows with the turn count,
+   capped at 30vh; once the cap is hit it scrolls internally. The scrollbar is
+   HIDDEN (scrollbar-width:none + webkit) so its appear/disappear never shifts
+   layout; scrolling is via wheel over the rail, the up/down buttons (click or
+   hover-hold), or the rail-top auto-load. Buttons are packed flush (no gap)
+   so hovering slides continuously without dead zones. */
+.tn-rail {
+  display: flex;
+  flex-direction: column;
+  width: 26px;
+  height: auto;
+  max-height: 30vh;
+  min-height: 0;
+  overflow-y: auto;
+  overflow-x: hidden;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.tn-rail::-webkit-scrollbar {
+  display: none;
+  width: 0;
+  height: 0;
+}
+/* Per-turn hotspot: a wider/taller transparent button so the tiny capsule
+   still has a comfortable hover/click target. Fixed size — excess turns make
+   the rail scroll, they never compress it. */
+.tn-cap-btn {
+  flex: none;
+  min-height: 10px;
+  width: 100%;
+  padding: 0;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  outline: none;
+}
+/* The visible capsule itself: grey, ~3px tall, ~12px wide by default. The
+   hover widening uses transform:scaleX (NOT width) with transform-origin on
+   the RIGHT, so it grows LEFTWARD only (right-aligned — the right edge never
+   moves), never reflows the rail or adds a horizontal scrollbar. */
+.tn-cap {
+  width: 12px;
+  height: 3px;
+  border-radius: 2px;
+  background: var(--dsw-alias-border-l3);
+  transform-origin: right center;
+  transition: transform 160ms ease, background 160ms ease, box-shadow 160ms ease;
+  flex: none;
+}
+/* Hovered capsule: glow with the theme's primary label color and widen 150%
+   (the wave peak). Theme-following (dark theme = white, light theme = dark). */
+.tn-cap-btn.tn-cap-hot .tn-cap {
+  transform: scaleX(1.5);
+  background: var(--dsw-alias-label-primary);
+  box-shadow: 0 0 6px color-mix(in srgb, var(--dsw-alias-label-primary) 55%, transparent);
+}
+/* Adjacent capsule: slightly wider (125%) — the wave's near neighbours. */
+.tn-cap-btn.tn-cap-warm .tn-cap {
+  transform: scaleX(1.25);
+  background: var(--dsw-alias-label-secondary);
+}
+/* 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. */
+.tn-tip {
+  position: fixed;
+  right: 40px; /* rail 26px + wrapper right 6px + 8px gap */
+  z-index: 100;
+  width: max-content;
+  max-width: 50vw;
+  padding: 3px 7px;
+  border-radius: 8px;
+  background: var(--dsw-alias-tooltip-bg);
+  color: var(--dsw-static-neutral-bluish-00);
+  font-size: 13px;
+  line-height: 20px;
+  white-space: pre-line;
+  overflow-wrap: break-word;
+  pointer-events: none;
+  animation: tn-tooltip-in 150ms var(--ds-ease-in-out);
+}
+@keyframes tn-tooltip-in {
+  from { opacity: 0; }
+}
+
+/* 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); }
+  100% { background: transparent; }
+}
+.tn-jump-highlight {
+  animation: tn-highlight-flash 1500ms ease-out;
+  border-radius: 4px;
+}
+`;
+		/**
+		* Inject {@link TURN_NAV_STYLES} once, tagged by plugin id so re-evaluation
+		* and repeated mounts stay idempotent (mirrors the dsh-kanban pattern).
+		* @param pluginId - stable plugin id used as the style tag marker.
+		*/
+		function injectTurnNavStyles(pluginId) {
+			if (typeof document === "undefined") return;
+			const selector = `style[data-dsh-plugin-css="${pluginId}"]`;
+			if (document.querySelector(selector) !== null) return;
+			const tag = document.createElement("style");
+			tag.setAttribute("data-dsh-plugin-css", pluginId);
+			tag.textContent = TURN_NAV_STYLES;
+			document.head.appendChild(tag);
+		}
+		injectTurnNavStyles("dsh-turn-navigator");
+		//#endregion
+		//#region src/client/index.ts
+		/** Dictionary namespace owned by this plugin. */
+		const NS = "dsh-turn-navigator";
+		/** Required services (cordis fiber inject). */
+		const inject = ["slots", "locale"];
+		/**
+		* Browser plugin body: registers the turn rail into the session header
+		* utilities seat.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			ctx.effect(() => ctx.locale.register(NS, {
+				zh,
+				en
+			}), "dsh-turn-navigator: copy dictionaries");
+			const t = ctx.locale.bind(NS);
+			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 })
+			}, TurnNavRail));
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,4 @@
+//#region src/index.ts
+function apply(_ctx) {}
+//#endregion
+export { apply };

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "dsh-turn-navigator",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-web-react",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "bundle": "tsdown --config ./tsdown.config.ts",
+    "prepare": "tsdown --config ./tsdown.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc --noEmit",
+    "release:check": "node scripts/release-check.mjs",
+    "prepack": "node scripts/release-check.mjs",
+    "prepublishOnly": "node scripts/release-check.mjs && tsdown --config ./tsdown.config.ts",
+    "postpublish": "node scripts/post-publish-check.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "turn",
+    "navigation",
+    "conversation",
+    "outline"
+  ],
+  "author": "karoc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karoc/dsh-turn-nav.git"
+  },
+  "bugs": {
+    "url": "https://github.com/karoc/dsh-turn-nav/issues"
+  },
+  "homepage": "https://github.com/karoc/dsh-turn-nav",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "^19.2.4",
+    "react": "^18.2.0",
+    "tsdown": "^0.22.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  }
+}