# dsh-webui-background

[简体中文](README.md)

`dsh-webui-background` is a standalone [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that adds a configurable background to the Web UI. It installs through the Harness bundle and client-plugin extension points; it does not modify or replace files under `website/public` or `apps/web/public`.

## Features

- An embedded “Web UI background” settings tab with upload, drag-and-drop, and preview.
- PNG, JPEG, GIF, and WebP support, detected from file bytes, with a 20 MiB limit.
- Separate light- and dark-theme readability masks, applied immediately after saving.
- Disable the background without deleting it, or reset to remove it and restore the stock UI.
- Per-profile image and settings storage.
- Read-only settings over remote connections; mutations require a loopback Web UI connection.

## Install

This plugin requires a DeepSeek Harness release with external bundles and browser client plugins (`0.1.0-rc.5` or newer).

```sh
dsh plugin --profile web add dsh-webui-background@next
dsh web
```

Restart an already-running Web UI. Then open “Settings → Plugins → Web UI background”, choose an image, and save.

To uninstall:

```sh
dsh plugin --profile web remove dsh-webui-background
```

Uninstalling does not remove profile data. Use “Reset to defaults” in the plugin first if you also want to remove the stored image.

## File names

The uploaded source may have a normal `.webp`, `.png`, or other supported extension. The plugin detects the format from its contents. Its private profile copy uses an extensionless content-hash name by design. The browser receives it from `/webui-background` with the detected `Content-Type`, so the stored file does not need an extension.

Each profile stores data under its own `data/webui-background/` directory. `state.json` contains the switch, masks, and revision; the image is named `background-<sha256>`.

## Develop from source

```sh
git clone https://github.com/lx963/dsh-webui-background.git
cd dsh-webui-background
pnpm install
pnpm test
pnpm build
dsh plugin --profile web add .
```

`prepack` emits the Host ESM bundle, browser CJS bundle, and declarations. Development requires Node.js `^22.19.0 || >=24` and pnpm 10.

## Security and limits

- SVG is excluded because it may contain active content.
- Image magic bytes are authoritative; the extension and browser-provided MIME type are not trusted.
- Image responses use `no-store` and `nosniff`; the URL revision only refreshes the current image in the page.
- A profile retains one current image, and optimistic revisions prevent browser tabs from silently overwriting one another.

## License

[MIT](LICENSE)