dsh-lifeline

Readme

<p align="right"><b>English</b> · <a href="README.zh-CN.md">简体中文</a></p>

<h1 align="center">DSH Lifeline</h1>

<p align="center">
  <strong>Right-side message navigation rail for DeepSeek Harness.</strong><br>
  Per-message tick marks · hover preview drawer · smooth jump · star bookmarks · realtime slide animation
</p>

<p align="center">
  <img src="https://img.shields.io/npm/v/dsh-lifeline?style=flat&label=latest%20release&color=4D6BFE" alt="Latest release">
  <img src="https://img.shields.io/npm/dt/dsh-lifeline?style=flat&label=total%20downloads&color=4D6BFE" alt="Total downloads">
  <a href="https://github.com/Physicolor/dsh-lifeline/stargazers"><img src="https://img.shields.io/github/stars/Physicolor/dsh-lifeline?style=flat&label=%E2%98%85&color=08C" alt="GitHub stars"></a>
  <img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat" alt="MIT License">
  <img src="https://img.shields.io/badge/DSH%200.1.x-4493F8?style=flat-square" alt="Supported: DeepSeek Harness 0.1.x">
</p>

---

> **TL;DR:** A persistent right-side rail that turns your conversation history into a navigable timeline — hover to preview, click to jump, star to bookmark. Built with official `--dsw-*` tokens for seamless integration with the DSH ecosystem.

DSH Lifeline is a **persistent DSH bundle plugin** built on the Cordis composition model. It renders a vertical navigation rail on the right side of the conversation page, with per-message tick marks that track your scroll position in real time. Hovering expands a preview drawer; clicking jumps to any historical message with smooth scrolling. The rail dynamically avoids other right-side panels (widgets, sidebar, etc.) and slides in/out with a coordinated animation when panels open or close.

---

## Features

### Navigation Rail

| Capability | Detail |
| --- | --- |
| Per-message ticks | Every user message generates one tick mark on the vertical rail |
| Scroll-spy highlight | The tick nearest to your current reading position lights up in brand blue |
| Center-axis alignment | The rail's center axis aligns with the message layout's content edge — no content occlusion |
| Always visible | Stays pinned on the right side; auto-hides when the session has < 2 user messages |
| Narrow-screen adaptive | Auto-hides at viewport ≤ 767px (mobile / narrow windows) |

### Hover Preview Drawer

| Capability | Detail |
| --- | --- |
| Hover to expand | Mousing over the rail expands a 260px-wide preview drawer with message text |
| Smooth slide | The drawer slides in from the right with a CSS transition (interruptible) |
| Click to jump | Clicking any item smoothly scrolls the chat to that message (loads older history on demand) |
| Star bookmarks | Click ★ to star a message; starred ticks glow gold in the collapsed rail; "★ Marked only" filter in the drawer |
| Virtualized list | Drawer uses a virtual list (30px row height); smooth even with thousands of turns |
| Official tokens | Background `--dsw-alias-bg-layer-1`, border `--dsw-alias-border-l2`, shadow `--dsw-shadow-lv3` — matches DSH input box / widget panels in both themes |

### Realtime Slide Animation

| Capability | Detail |
| --- | --- |
| Frame-by-frame sync | When a right-side panel (widgets, sidebar) opens or closes, the rail follows the conversation-area width change every frame |
| 220ms ease-out tween | Smooth entry/exit with interruptible animation — rapid open→close→open animates seamlessly |
| Content-flow reference | Positioning uses the conversation content-flow container's live rect; no stale overlay caches |

### Session Index + Rewind

| Capability | Detail |
| --- | --- |
| Full session index | Host REST endpoint (`/api/chat-timeline-index`) serves the complete user-message index with incremental pushes |
| No page-load needed | Long conversations show every historical tick without paging through "load earlier" |
| Rewind integration | Withdrawn / rewound messages are automatically removed from the timeline via `dsh-rewind` |

### Panel Avoidance

| Capability | Detail |
| --- | --- |
| Dynamic right-edge tracking | Detects right-side workbenches (`dsh-better-sidebar`, `dsh-widgets`, `aionui`) and shifts to align |
| Multi-panel aware | Handles two overlapping right panels simultaneously |

---

## Architecture

- **Host half** (`lib/index.js`): registers the `dshChatTimeline` session projection + REST index endpoint (`/api/chat-timeline-index`) for full-history access;
- **Client half** (`lib/client.js`): exports `{ name, inject, apply }` via `window.__ModuleLoader__`; the `TimelineRail` component is mounted on the `conversation.input.dock` slot and portal-rendered to `document.body`;
- **Positioning engine**: measures the content-flow container's `getBoundingClientRect()` every frame; the rail center axis targets the layout's `padding-box` right edge (e.g. `Md3f7G_scroll`'s 32px right padding);
- **Styling**: all surfaces use `--dsw-*` semantic tokens — no hard-coded rgba, automatic light/dark adaptation;
- **Data pipeline**: REST incremental index → session projection → loaded chat nodes → on-demand `loadOlder` (fastest first).

---

## Installation

### via npm (recommended)

```sh
dsh plugin --profile web add dsh-lifeline
```

Then restart `dsh web` and hard-refresh the browser.

### local development (link)

```sh
# 1. Clone the repo
git clone https://github.com/Physicolor/dsh-lifeline.git

# 2. Link in your profile
#    In $DSH_HOME/profiles/web/package.json, add:
#    "dsh-lifeline": "link:../../plugins/dsh-lifeline"
cd $DSH_HOME/profiles/web && pnpm install

# 3. Restart dsh web
```

---

## Changelog

### v0.1.0 (2026-09-01)

Initial release as an independent project (formerly `dsh-chat-timeline`):

- **Rewritten positioning engine** — frame-by-frame follow of the content-flow container's live rect; compatible with `dsh-better-sidebar` / `dsh-widgets` / `aionui` panel avoidance
- **Full session index** — host REST endpoint serves complete message history with incremental pushes; no need to page through "load earlier"
- **Virtualized rendering** — drawer virtual list + tick neighbourhood slice; smooth on thousands of turns
- **Center-axis alignment** — rail center axis aligns with `Md3f7G_scroll` padding-box right edge (previously offset by the content padding)
- **Realtime slide animation** — frame-by-frame sync with panel open/close; 220ms ease-out tween with interrupt support
- **Official-token styling** — drawer and collapsed capsule use `--dsw-*` tokens (`layer-1` / `border-l2` / `shadow-lv2` / `shadow-lv3`); dual-theme adaptive, no hard-coded rgba

---

## Acknowledgments

This project builds on source code from [jjxjjjjiik-bot/dsh-chat-timeline](https://github.com/jjxjjjjiik-bot/dsh-chat-timeline) (MIT). The plugin architecture was originally modeled on [asukasec/dsh-message-preview](https://github.com/asukasec/dsh-message-preview) (MIT).

---

## License

MIT © [Physicolor](https://github.com/Physicolor)