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.

(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

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

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