@dsh-external/dsh-conversation-minimap

Readme

[中文说明](./README.zh-CN.md)

# dsh-conversation-minimap

`@dsh-external/dsh-conversation-minimap` adds a Codex-style conversation
minimap to DeepSeek Harness. One marker represents one engine-owned turn. The
current reading turn is emphasized, hover or keyboard focus opens a compact
preview, and activating a marker scrolls directly to that turn.

The preview is derived from Harness's public conversation snapshot and can
show:

- the user request summary;
- the latest assistant result summary;
- running, completed, failed, or stopped status;
- files produced by the optional `ui-deliverables` feature.

The plugin is additive. It registers a layout-neutral entry in
`conversation.session.header.utilities`, locates that session's semantic
`[data-conversation-scroll]`, and renders the rail through its own portal. It
does not replace the conversation body, change the conversation width, scrape
rendered prose, or depend on CSS-module hashes.

## Install

Build the source checkout and add it to an isolated Harness Web profile:

```powershell
pnpm install
pnpm run build

cd C:\Users\lumoren\Documents\GitHub\deepseek-harness
pnpm dsh plugin --profile web add C:\Users\lumoren\Documents\GitHub\dsh-conversation-minimap
pnpm dsh web
```

For source rebuilds without restarting the host, run `pnpm run dev:web` from
the Harness checkout in a second terminal.

## Behavior

- Wide conversation columns receive a left-side rail with exactly one visual
  mark and one accessible button per turn. Short histories stay in a compact,
  fixed-spacing cluster around the rail center; long histories progressively
  expand through the available height. Only the active reading turn receives
  the long, high-contrast mark.
- Narrow columns receive a compact header utility that opens the same rail.
- Hover and focus show a wide, theme-token glass preview with crisp request and
  result text, status, and up to four produced paths. The preview keeps its
  pointer handoff when the cursor moves from a marker into the card.
- Click, Enter, or Space scrolls to the first mounted row for the turn.
- Earlier history is loaded only on request; the current reading anchor is
  preserved while the older page is inserted.
- Conversation opening, older-page loading, and a failed page request are
  surfaced in the rail without replacing the host conversation status.
- Every marker is a real button with an accessible label and `aria-current` on
  the active reading turn.
- `prefers-reduced-motion` is observed live. Smooth scrolling and transient
  movement are removed when reduction is requested.

An application or theme can disable the minimap for a subtree:

```html
<section data-dsh-conversation-minimap="off">...</section>
```

## Compatibility

The package targets the semantic conversation contracts in Harness
`0.1.0-rc.5` and the published `0.1.0-rc.6` client line. It is tested with the
default `light` and `dark` themes plus `angelina-light` and `angelina-dark`.
Theme colors come from `--dsw-alias-*` tokens with system-color fallbacks.

The plugin is independent of `dsh-motion`. Its own portal opts out with
`data-dsh-motion="off"` to prevent duplicate motion; the surrounding Harness
surface remains under normal host and theme ownership.

## Development

```powershell
pnpm run check
pnpm run pack:check
```

Optional Playwright acceptance tests use an already running isolated profile:

```powershell
$env:DSH_MINIMAP_E2E_URL = 'http://127.0.0.1:3000/'
pnpm run test:e2e
```

The runtime has no polling loop, interval, or permanent animation frame. Its
MutationObserver is scoped to the active conversation scrollport; all
observers, listeners, portal nodes, styles, timers, and requested frames are
released with the session entry.

## Distribution faces

- `.`: no-op Node half mounted by the Harness Loader.
- `./client`: browser Cordis plugin registered through `__ModuleLoader__`.
- `./cordis.patch.yml`: profile patch that adds the Loader row.

MIT licensed.