dsh-beacons

dsh-beacons

Codex/OpenChamber-style prompt-navigator rail with scroll-spy — a DeepSeek Harness (DSH) Web UI plugin.

中文说明见 README.zh.md。

A scrub rail (提示词导航条) sits on the right edge of the conversation, one tick per real user prompt. As you scroll, the tick for the prompt you are reading stays highlighted; hover to preview, click to jump.

Design reference — the navigator interaction (scrub rail, scroll-spy reading-line, hover wave, preview panel, edge carousel, listbox keyboard semantics, load-earlier) is adapted from OpenChamber (github.com/openchamber/openchamber):

• packages/ui/src/components/chat/components/PromptNavigatorRail.tsx
• packages/ui/src/components/chat/lib/scroll/scrollSpy.ts

Quick start

dsh plugin --profile web add github:Da-Mie/dsh-beacons

Restart DSH and refresh the Web UI. The rail appears on the right edge of any session with ≥ 2 user prompts; press Alt+P for keyboard navigation.

Features

Prompt navigator (Web UI)

• Always-on right-edge rail — anchored to the conversation column's right edge (never overlaps the details panel) and vertically centered; shown once the session has ≥ 2 real user prompts.
• Scroll-spy — a reading-line algorithm highlights the prompt at the current reading position (top + 100 px); near the bottom, the last prompt is highlighted. Monotonic, so there is no flip-flop inside a long prompt. rAF-throttled, with ResizeObserver + MutationObserver refresh.
• Hover wave — ticks near the cursor grow longer and their neighbors taper off (Codex-style proximity wave).
• Hover preview panel — a gliding mini-list (up to 8 rows) with the highlighted row centered; the wheel steps row by row; rows are clickable.
• Windowed tape — at most 30 ticks are visible; hovering the gutter's top/bottom edges scrolls the window through longer histories.
• Auto-load earlier history — scrolling to the top automatically loads older history (threshold max(900px, 1.5 × viewport), 1.2 s cooldown between loads); a ↑ load-earlier button above the gutter offers manual control.
• Click to jump — clicking a tick or a preview row smooth-scrolls the chat to that prompt.
• Keyboard — Alt+P opens keyboard navigation (listbox semantics): ↑/↓ move, Home/End jump, Enter selects, Esc closes.
• Filtering — only real user prompts are indexed (user + steering nodes); injected context is excluded.

Requirements

• DeepSeek Harness ≥ 0.1.0-rc.6 (Web UI profile; check with dsh --version)
• Node.js ≥ 22 (only needed to build from source)

Installation

The package ships prebuilt (lib/ is committed), so every install path works with no build step.

Install with DSH (AI)

Just hand this repository URL to your DSH agent:

https://github.com/Da-Mie/dsh-beacons

DSH reads the repository's AGENTS.md and installs the plugin automatically (requires DSH ≥ 0.1.0-rc.6). The command-based methods below achieve the same result.

From GitHub

dsh plugin --profile web add github:Da-Mie/dsh-beacons

From a tarball

dsh plugin --profile web add ./dsh-beacons-0.1.0.tgz

Via npm

dsh plugin --profile web add dsh-beacons

Requires the package to be published to the npm registry first (see Development).

After installing, restart DSH (plugin-set changes take effect on restart), then refresh the Web UI.

Usage

• Open — the rail appears automatically on any session with ≥ 2 prompts; press Alt+P to focus it for keyboard control.
• Scroll — the highlighted tick follows the prompt you are reading; at the bottom it settles on the last prompt.
• Preview — hover a tick to see the preview list on its left.
• Jump — click a tick or a preview row to scroll the chat to that prompt.
• Load more — click the ↑ button above the gutter, or simply scroll to the top to load earlier history automatically.
• Keyboard (after Alt+P) — ↑/↓ move, Home/End jump, Enter selects, Esc closes.

Development

npm install
npm run build

The client bundle (lib/client.js) is a window.__ModuleLoader__.load({ id, factory }) CJS factory served by DSH's client-modules service at /plugins/<id>/client.js.

Architecture

• src/index.ts — host half: a no-op entry (the navigator is browser-only).
• src/client/index.tsx — client entry: session feed (sessions list → binding → conversation snapshot), Alt+P shortcut, shell.overlay registration.
• src/client/store.ts — module-level navigation state (a root-scoped overlay entry cannot receive the session kit).
• src/client/scroll-spy.ts — reading-line scroll-spy (a port of OpenChamber's scrollSpy.ts).
• src/client/PromptNavRail.tsx + .module.css — the rail component (a port of OpenChamber's PromptNavigatorRail.tsx).

Known limitations

• Only history loaded into the chat window is navigable; older prompts appear after loading earlier history (auto or manual).
• Previews show text content only.

License

MIT