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 running DSH web profile ($DSH_HOME/profiles/web, e.g. \.dsh\profiles\web).

Via pnpm (recommended)

# from your plugin checkout
dsh plugin --profile web add "file:
"

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 "
   

"

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

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

3. Hard-reload the browser page (Ctrl+Shift+R). Open Settings → General — the Background image row appears there.

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.