dsh-plugin-webui-bg

A DeepSeek Harness (DSH) WebUI plugin: pick a local image as the WebUI background, overlaid with a translucent mask that matches the current theme (light / dark), so the image never disturbs the UI's readability.

Features

• A Background image row in Settings → General:
  • Pick a local image (browser file picker), or use the built-in Sample image to try it instantly
  • Images are downscaled (max edge 1920px) and re-encoded (WebP, JPEG fallback) before persistence
  • Live preview thumbnail
  • Enable / disable toggle
  • Mask opacity slider (50%–100%, default 75%)
  • Background blur slider (0–40px, default 0)
  • One-click Remove background
• The mask color uses the theme token --dsw-alias-bg-base, so it follows the light/dark theme automatically.
• Both background layers are pointer-events: none fixed layers — they never block interaction.
• Privacy: the image never leaves your browser. It is stored in localStorage (key dsh.webui-bg); no network requests are made.

How it works

The DSH layout frame and its full-viewport children (body, sidebar column, conversation root, …) carry their own opaque backgrounds that would otherwise paint over the background layers. The plugin:

1. Appends two fixed layers to document.body: the image behind, the theme-colored mask in front (both pointer-events: none).
2. Neutralizes every large fully-opaque "surface" container it finds under the layout frame (size heuristics, no hashed-class dependence), so the layers show through. Cards, buttons and bubbles keep their own backgrounds for readability.
3. Skips overlay-like subtrees (modals, popovers, tooltips — anything fixed/absolute or with a positive z-index), so dialogs stay opaque.
4. Watches the DOM with a MutationObserver and re-neutralizes on remounts; restores the original backgrounds when the background is disabled.

Persistence is browser-local on purpose: DSH's API gateway only exposes allowlisted settings namespaces to configuration clients, so a third-party namespace would be refused on the wire.

Compatibility

⚠️ This plugin targets DSH internal APIs that may change between releases. It was built and verified against @deepseek-ai/dsh 0.1.0-rc.6.

Dependencies on DSH internals:

Surface	What it relies on
Client bundle format	window.__ModuleLoader__.load, dsh.client in package.json
Settings row	the settings.general.item slot and the slots / locale services
Theme mask	the --dsw-alias-bg-base CSS token and body[data-ds-dark-theme]
Surface neutralization	the layout frame structure ([data-shell-overlay] parent) and size/opacity heuristics

If a DSH update changes any of these, the plugin may need adjustments.

Install

Requires a DSH web profile on the target machine ($DSH_HOME/profiles/web, e.g. <user-home>\.dsh\profiles\web; boot it once with dsh web if it does not exist yet). No build step, no runtime dependencies.

One-click installer (recommended)

Easiest: double-click scripts\install.cmd — it wraps the PowerShell installer with -ExecutionPolicy Bypass, so it works even where running .ps1 scripts is restricted.

Or run the PowerShell installer directly from the plugin directory:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

If you get "…禁止运行脚本" (execution policy) when running .\install.ps1 directly, either use the .cmd wrapper above, pass -ExecutionPolicy Bypass, or allow local scripts for your user once:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

The installer links the package into the profile's module directory (junction, copy fallback) and appends the loader insert row to cordis.patch.yml (idempotent — safe to re-run). Customize the profile / DSH home with -ProfileName and -DshHome.

Via pnpm

# from your plugin checkout
dsh plugin --profile web add "file:<path-to-this-package>"

Manual (no pnpm)

1. Link the package into the profile's module directory (one junction, no dependencies to link — the node half is a no-op):

   New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\node_modules\dsh-plugin-webui-bg" -Target "<path-to-this-package>"
   

2. Append an insert row to profiles\web\cordis.patch.yml (the patch layer hot-reloads, no process restart needed):

   - insert:
       - id: webui-bg
         name: dsh-plugin-webui-bg
   

After installing (all methods)

1. Hard-reload the browser page (Ctrl+Shift+R).
2. Open Settings → General — the Background image row appears there; pick a local image (or the built-in Sample).
3. Persistence is per-browser (localStorage), so a fresh machine starts without a stored background until you pick one.

Uninstall

• Remove the insert row from cordis.patch.yml.
• Delete the profiles\node_modules\dsh-plugin-webui-bg link.
• Optional: run localStorage.removeItem("dsh.webui-bg") in the browser console to clear the stored image.

Package layout

File	Purpose
lib/index.js	Host half: a no-op apply so the loader mounts the entry and serves the client bundle.
lib/client.js	Browser half (dsh.client.platform: "web" client bundle): background layers, settings row, localStorage persistence.
package.json	Plugin manifest: dsh.client declaration, ./client export.

lib/client.js is a hand-written bundle in DSH's lazy-CJS client format (no build step) — keep it in sync with the format if you refactor.

License

MIT — see LICENSE.