Initial commit: dsh-history-nav DSH plugin with docs

2026-10-10 17:37:32 +00:00
commit 78ff986584
@@ -0,0 +1,66 @@
+# dsh-history-nav
+
+Browser history and deep-link URLs for the DeepSeek Harness (DSH) Web UI.
+
+The DSH shell keeps its navigation (selected session, central panel, settings dialog/section) in memory only, so the browser **Back/Forward** buttons and page reloads lose your place. This client plugin mirrors that state into the URL hash and the browser history.
+
+## Features
+
+- URL hash reflects where you are:
+  ```
+  #/session/<id>[/parent/<id>/mode/<m>][/panel/<id>][/settings/<section>]
+  ```
+- Every user navigation does `history.pushState`, so **Back/Forward** work; changes during app startup use `replaceState`.
+- `popstate` / `hashchange` / loading a page with a hash restores the state (shareable, bookmarkable links to sessions, panels and settings sections).
+- Mouse buttons 4/5 (Back/Forward) map to `history.back()` / `history.forward()`.
+
+## How it works
+
+| File | Role |
+| --- | --- |
+| `client.js` | Web client module (`@local/dsh-history-nav`), injects `@deepseek-ai/dsh-client-ui-layout` and `@deepseek-ai/dsh-client-ui-workspace`; owns all behaviour. |
+| `index.js` | Empty Host half (`apply() {}`). |
+| `cordis.patch.yml` | Bundle patch inserting the `dsh-history-nav` row. |
+
+## Installation
+
+Requirements: a working DeepSeek Harness (`dsh`) install with the **web** profile (or any profile that includes the Web UI).
+
+### Option A — install from git (recommended)
+
+```bash
+dsh plugin --profile web add git+https://git.rizzy.dev/DSH-Plugins/dsh-history-nav.git
+```
+
+You can also paste `git+https://git.rizzy.dev/DSH-Plugins/dsh-history-nav.git` into **Settings → Plugins → Install** in the Web UI, or ask the agent to install it with its `plugin_manager` tool (`install_bundle`).
+
+The plugin manager adds `@local/dsh-history-nav` to `dependencies` and to `dsh.profile.bundles` in `~/.dsh/profiles/web/package.json`.
+
+### Option B — local checkout (for development)
+
+```bash
+git clone https://git.rizzy.dev/DSH-Plugins/dsh-history-nav.git ~/dsh-plugins/dsh-history-nav
+dsh plugin --profile web add link:$HOME/dsh-plugins/dsh-history-nav
+```
+
+With a `link:` install, edits in the checkout are picked up directly (client changes reload on page refresh, Host changes after a DSH restart or HMR reload).
+
+### Enable / verify
+
+1. Make sure `@local/dsh-history-nav` is listed in `dsh.profile.bundles` of `~/.dsh/profiles/web/package.json` (the installer does this; add it by hand if you edited `package.json` manually).
+2. Restart DSH (`dsh web`) or reload the page.
+3. Check **Settings → Plugins**: the `@local/dsh-history-nav` bundle should be enabled.
+
+### Uninstall
+
+```bash
+dsh plugin --profile web remove @local/dsh-history-nav
+```
+
+### Updating
+
+Re-run the `add` command from Option A (or `git pull` in your Option B checkout).
+
+## Configuration
+
+None. Once enabled, open a session and watch the address bar update; use Back/Forward or reload the page to verify restoration.