dsh-floor-nav

Readme

# dsh-floor-nav

[English](./README.md) | [简体中文](./README.zh-CN.md)

DeepSeek Harness community plugin: a **LiveAgent-style floor navigation rail** for the [web GUI](https://github.com/deepseek-ai/deepseek-harness).

- **Collapsed:** a thin column of short horizontal tick marks on the conversation’s right edge (sampled user turns)  
- **Expanded:** hover opens a glass panel listing every user message; click jumps the transcript  
- **Pins (★):** optional bookmarks per session (`localStorage`)  
- Clears **dsh-better-sidebar** via `--dsh-sidebar-width` and the composer via `--dsh-composer-height`

## Credits / prior art

**UI behavior and interaction model are adapted from [LiveAgent](https://github.com/thirsty5034/LiveAgent)** (open source):

| LiveAgent source | Role |
|------------------|------|
| `crates/agent-ui/src/pages/chat/transcript/FloorNavRail.tsx` | Rail UI: collapsed markers, hover panel, touch reveal, pin rows |
| `crates/agent-ui/src/lib/chat-floor-nav/floorModel.ts` | Floor list, preview truncation, marker sampling, nearest active mark |
| `crates/agent-ui/src/lib/chat-floor-nav/floorBookmarks.ts` | Per-conversation pin persistence |

This package is a **DSH-native reimplementation** (Cordis client plugin + DSH conversation snapshot / `[data-chat-anchor-key]` jump). It is **not** a fork of the LiveAgent repository and does not ship LiveAgent code as a dependency. LiveAgent remains under its own license; please respect upstream terms when consulting that codebase.

## Requirements

- DSH **web** profile  
- Optional: [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar) (layout offset is a no-op if absent)

## Install

**macOS / Linux:**

```sh
curl -fsSL https://raw.githubusercontent.com/thirsty5034/dsh-floor-nav/main/scripts/install.sh | bash
```

**Windows (PowerShell):**

```powershell
irm https://raw.githubusercontent.com/thirsty5034/dsh-floor-nav/main/scripts/install.ps1 | iex
```

Or CLI (GitHub until npm publish):

```bash
export DSH_HOME=${DSH_HOME:-$HOME/.dsh}
dsh plugin --profile web add "dsh-floor-nav@github:thirsty5034/dsh-floor-nav"
dsh --profile web --dump-config | grep floor-nav
```

Restart DSH web after install, then **hard-refresh** the browser. The rail appears when the current session has **≥ 2** visible user (or steering) messages.

<details>
<summary><b>Options / local link / npm (later)</b></summary>

```sh
bash scripts/install.sh --restart
bash scripts/install.sh --from npm 0.1.0
dsh plugin --profile web add "dsh-floor-nav@link:/path/to/dsh-floor-nav"
```

</details>


## Discoverability

- GitHub topics: `dsh-plugin`, `deepseek-harness`, `dsh` (required for [dsh.so](https://www.dsh.so/) auto-index)
- Install from GitHub (current): see **Install** above
- Store listings may lag crawlers; source of truth is this repository


## Behavior

| State | Interaction |
|-------|-------------|
| Collapsed | Height-adaptive sampled ticks (desktop ≤40, touch ≤12); pinned floors always kept |
| Expand | Mouse enter → panel; leave → collapse after 160ms; touch: tap rail / outside to close |
| Jump | Scrolls `[data-conversation-scroll]` to `[data-chat-anchor-key]` |
| Active floor | Nearest user row to the upper-quarter of the viewport; highlight nearest sampled tick |
| Pins | `localStorage["dsh-floor-nav.bookmarks.v1"]` |

## Development

```bash
npm run check
```

Host half is an empty Cordis shell; all UI lives in `lib/client.js` (ModuleLoader client bundle).

## License

MIT — see [LICENSE](./LICENSE).

LiveAgent is a separate project; this plugin only **references** its floor-nav design.