dsh-plugin-background

Readme

# dsh-plugin-background

> Background image plugin for the **DeepSeek Harness web UI** (`dsh web`).

Pick a local image as the background of the whole interface, adjust a
theme-aware readability matte, or clear it — anytime, from a button at the
bottom of the sidebar. The image is compressed client-side and persisted in
IndexedDB, so it survives restarts with zero server-side storage.

> ⚠️ Third-party community plugin — not an official DeepSeek product.
> Built for [`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness).

*(Add a screenshot under `docs/` and reference it here once you have one.)*

## Features

- Upload any local image (PNG / JPG / WebP) as the full-UI background
- 🎨 Built-in preset backgrounds (one-click gradient themes)
- Three display modes: stretch-to-fill (whole image, no cropping), cover (fill, cropped), contain (whole image, letterboxed)
- High-quality client-side compression (up to 4096 px edge, WebP-first, smooth scaling)
- Theme-aware readability matte (0–80 %, white in light mode / dark in dark mode)
- ✏️ Adjustable text outline (0–100 %) keeps chat readable without dimming the image
- One-click clear, back to the default theme
- Persisted in IndexedDB — large images, survives restarts, no server involved
- Hot-reload friendly (`pnpm run dev:web` watcher), HMR-safe style/theme cleanup

## How it works

- Pure browser-side Cordis client plugin registered in the `sidebar.footer.action` slot.
- The image lives on a single body-level background (`background-attachment: fixed`),
  with a theme-aware matte on top. `--dsw-alias-bg-base` is overridden to
  `transparent` and the sidebar fill is made transparent too, so the frame, chat
  column, details column and sidebar all let that one background show through —
  one seamless sheet across the whole UI (no per-region images that can misalign).
- The readability matte is a `color-mix` layer over the base palette token
  (white in light mode / dark in dark mode), so text stays readable over any
  image; no DOM selectors are touched.

## Requirements

- A running `dsh web` profile (DeepSeek Harness, ≥ 0.1.0-rc.6)
- `pnpm` (or `npm exec` with a writable cache dir)
- A Chromium/Firefox-class browser

## Usage

1. Start `dsh web` and open the GUI.
2. Click the **Background** button at the bottom of the sidebar (next to Settings).
3. Choose a local image — it is applied immediately.
4. Use the matte slider to balance readability; click **Clear background** to reset.

## Development

```bash
git clone <repo-url> && cd dsh-plugin-background
node build.mjs          # build once → dist/client.js
node build.mjs --watch  # rebuild on src/client.js changes
```

- `src/client.js` is the only file you normally edit (plain JS, `React.createElement`, no JSX/TS).
- `dist/client.js` is committed on purpose so users can install without building.
- After changing `src/`, rebuild, then restart `dsh web` (or run the `pnpm run dev:web`
  watcher from the harness checkout for hot reload).

## Uninstall

```bash
cd ~/.dsh/profiles/web
pnpm remove dsh-plugin-background
# remove the ui-background row from cordis.patch.yml (if manual)
dsh web
```