Load Wallpaper Engine .mpkg files as the DSH web background: embedded video, time-of-day switching, unified frosted blur, local wallpaper library & rotation.
Install
# from npm (prebuilt)
dsh plugin --profile web add dsh-mpkg-wallpaper
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:XHR666/dsh-mpkg-wallpaper
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
Bring Wallpaper Engine wallpaper into the DeepSeek Harness Web UI.
dsh-mpkg-wallpaper is a wallpaper and UI-appearance plugin for DeepSeek Harness (dsh web). It parses Wallpaper Engine .mpkg files, Steam Workshop folders and video / web / scene wallpapers, and adds a full-screen blur system, transparent surfaces, theme colours, a Floating Island layout (floating cards), Now Playing, a wallpaper library and scheduled rotation.
What makes it different: it is not just a background image switch. It turns background, blur, transparency, floating cards and theme colours into one adjustable, restorable and diagnosable appearance system.
Contents
- Highlight: Floating Island
- Features
- Install
- Quick start
- Wallpaper sources and types
- Appearance system
- Playback, library and Now Playing
- Where the settings are
- Security and privacy
- Compatibility and limits
- Troubleshooting
- Development and gates
- File structure
- License
- Feedback
Highlight: Floating Island
Floating Island (also called Floating Cards) is the most recognisable UI feature of this plugin. It is enabled with Appearance → Floating effect (float).
When enabled:
- the left sidebar and title bar become rounded floating cards with shadows, revealing the wallpaper behind them;
- the wallpaper stays visible between and around the cards, creating an "island floating on the desktop" layering effect;
- it composes with full-screen blur, sidebar/title-bar opacity, theme colours and the mouse glow;
- turning it off restores the edge-to-edge layout without affecting the other transparency/blur settings;
- the floating geometry, the Now Playing card and the right-sidebar yield/expand logic are all covered by their own checks and recalibrated on window resize.
The most "island-like" look: enable Floating effect, lower the full-screen blur enough to let the wallpaper texture show through, and give the sidebar/title bar a suitable opacity.
Features
| Feature | Description |
|---|---|
Wallpaper Engine .mpkg |
Parse containers in the browser: video wallpapers play embedded video, scene wallpapers use a static frame/layer composition, and WE Time Variation is supported |
| Steam Workshop | Auto-discover Wallpaper Engine and steamapps/workshop/content/431960; each subfolder is a wallpaper |
| Video / image / web | Local video, images, animated images, URLs, and HTML wallpapers in a sandboxed iframe |
| Floating Island | Sidebar and title bar become rounded floating cards; combines with blur, shadow, transparency and theme colours |
| Blur system | One full-screen slider plus independent blur/transparency for the title bar, sidebars, dialogs, menus and masks |
| Theme and glass | Colour picker, accent colour, Aqua experiments, CSS liquid glass; all off by default, so stock DSH stays untouched |
| Playback & power saving | Play/pause; auto-pause on tab switch, window blur and battery power (configurable) |
| Library & rotation | Local folders, WE playlists, previous/next, 1–120 minute scheduled rotation |
| Now Playing | Sidebar player: wallpaper track list, play/pause, volume/seek, system media session (MPRIS/SMTC) |
| Scan wallpapers page | Right-sidebar thumbnail grid of the current folder; apply without leaving the page |
| Diagnostics & error log | One-click environment/render/settings snapshot; per-block error log with sanitized/full export; never uploaded automatically |
| Hybrid mode | .mpkg files are streamed to the DSH host and played over HTTP Range, so >600 MB files do not have to fit in memory |
Install
Requirements: a working dsh web; Node.js ≥ 20.
Option 1: dsh plugin add (recommended)
dsh plugin --profile web add dsh-mpkg-wallpaper
# restart dsh web, then press Ctrl+F5 in the browser
Option 2: pnpm
pnpm --dir "$DSH_HOME/profiles/web" add dsh-mpkg-wallpaper
# restart dsh web, then Ctrl+F5
Option 3: clone from GitHub (developers / offline)
git clone https://github.com/XHR666/dsh-mpkg-wallpaper.git \
"$DSH_HOME/profiles/web/node_modules/dsh-mpkg-wallpaper"
Then register it in $DSH_HOME/profiles/web/cordis.patch.yml:
- insert:
- id: dsh-mpkg-wallpaper
name: dsh-mpkg-wallpaper
Restart dsh web. This method does not write the dependency table, so the market may not show "installed"; functionality is unaffected.
Option 4: single-file bundle (offline / emergency; host side only)
node tools/build-bundle.mjs
node tools/build-bundle.mjs --check
node tools/bundle-equivalence-test.mjs
Copy dist/dsh-mpkg-wallpaper.bundle.mjs anywhere and register its absolute path in cordis.patch.yml:
- insert:
- id: dsh-mpkg-wallpaper
name: /absolute/path/dsh-mpkg-wallpaper.bundle.mjs
The single-file bundle contains the host side only (upload/Range/settings/diagnostics routes). The full client UI (settings panel, wallpaper layer, Floating Island, Now Playing) requires the full npm package. One-click update is not recommended in this mode.
Update
# Option 1 / 2
dsh plugin --profile web update dsh-mpkg-wallpaper
# Option 3
git -C "$DSH_HOME/profiles/web/node_modules/dsh-mpkg-wallpaper" pull
# Option 4
node tools/build-bundle.mjs # rebuild and replace the .mjs
After updating: restart dsh web → Ctrl+F5.
Uninstall and residual data
dsh plugin --profile web remove dsh-mpkg-wallpaper
Optional cleanup:
- browser
localStorage['dsh.mpkg-wallpaper.v2']; - main data directory
$DSH_HOME/.dsh-mpkg-wallpaper/(settings.json, uploaded.mpkgfiles, transcode cache,web-store.json, etc.); - diagnostics/thumbnails
~/.dsh/.dsh-mpkg-wallpaper/(diag-*.json,thumbs/).
The
desktopprofile of DSH Desktop is owned by the Electron shell and rejectsdsh plugin --profile desktop add. Use the desktop app's plugin UI, or put the package into that profile's dependency tree and keep thecordis.patch.ymlmount line.
Quick start
- Install, restart
dsh web, hard-refresh the browser. - Open Settings → DSH wallpaper engine from the left sidebar.
- In Background source, choose any source:
- drop an
.mpkg; - pick a local image/video;
- enter an image or web URL;
- choose a custom folder (you can select Steam's
steamapps/workshop/content/431960).
- drop an
- To change the look, start with:
- Wallpaper settings → blur;
- Unified appearance → full-screen blur;
- Appearance → Floating effect.
If something breaks, open Other → View error log or click One-click diagnostics, then attach the result to your report.
Wallpaper sources and types
| Source | What is supported |
|---|---|
.mpkg container |
Video, scene (static frame/layer composition), Time Variation assets, embedded audio |
| Steam Workshop | Video / web / scene wallpapers under steamapps/workshop/content/431960; non-default Steam libraries supported |
| Local folder | .mpkg, Workshop subfolders, images, videos and scene.pkg can be mixed |
| Image / animation | Local file or URL (including data:image) |
| Video | .mp4 / .webm / .mov / .m4v |
| Web wallpaper | HTML runs in a sandboxed iframe; configurable web options and interaction |
| Scene wallpaper | Rendered by the bundled WEwebLoader renderer in an iframe; static fallback and no-WebGL degradation |
Time Variation wallpapers
Recognises WE's morningtime / daytime / dusktime / nighttime / timevarying attributes:
- automatically picks the slot for the current local time;
- lazily loads only the current slot, not all slots at once;
- lets you lock a slot manually, and return to automatic mode;
- clears the previous wallpaper's slot cache when switching, avoiding cross-wallpaper leakage.
Hybrid mode
Enabled by default: .mpkg files are streamed to the DSH host via Range upload and stored on disk, then read on demand during playback — the whole container is not loaded into memory. Disabling it returns to browser-only parsing (limited by browser memory).
Appearance system
1. Floating Island
- Location: Appearance → Floating effect (off by default).
- Turns the left sidebar and title bar into rounded floating cards with shadows, revealing the wallpaper.
- Composes with sidebar/title-bar opacity, full-screen blur, theme colours and the mouse glow.
- Turning it off restores the edge-to-edge layout; existing transparency/blur settings are untouched.
2. Full-screen blur and transparency
- Unified blur: one slider controls wallpaper blur and the sidebar/title-bar white haze together; whether the chat area and new-session button follow is configurable.
- Independent blur: dialogs, settings, confirmation dialogs, menus/popovers, masks and the left sidebar each have their own switch and amount.
- Surface transparency: left sidebar, title bar and right sidebar/dock can reveal the wallpaper independently.
3. Theme colours, Aqua and glass
- Theme colour and brand accent colour are configurable separately.
- Aqua experiments (auto colour sampling from the wallpaper, text readability enhancement, task-list frost, etc.) are all off by default.
- CSS liquid glass can be applied to the composer, left sidebar and title bar; it does not need the WebGL runtime.
4. Mouse glow
A soft glow follows the pointer inside the panel under it. Turning it off stops the listener and writes no state. It is linked to the Floating effect and does nothing when floating is off.
Playback, library and Now Playing
Playback and power saving
- Video/web wallpapers can be paused/resumed; the state follows the real media element;
- power-saving policies: pause on tab switch, window blur and battery power (separately configurable); resume according to the previous state;
- changing appearance settings does not restart the playing wallpaper.
Library and rotation
- Scan wallpapers from Steam Workshop or a custom folder;
- import a WE playlist as the rotation list;
- previous/next switching; scheduled rotation every 1–120 minutes;
- checking list items does not scroll the list back to the top.
Now Playing
- Mounts a player card above the left sidebar's Settings entry (on by default);
- plays the wallpaper's audio track list, with play/pause, volume and seek;
- integrates with the system media session (MPRIS / SMTC) when the host supports it;
- automatically yields when another plugin already occupies the same sidebar slot.
Scan wallpapers page
The right-sidebar page shows a thumbnail grid of the current folder; select and apply a wallpaper, with name/container file/type in the details area. Previews are separated from the actual wallpaper so the list stays responsive.
Where the settings are
Left sidebar → Settings → DSH wallpaper engine, seven tabs:
| Tab | What is there |
|---|---|
| Background source | Master switch, hybrid, current wallpaper, file/folder/URL pickers |
| Wallpaper settings | Blur, zoom/offset, flip, brightness, playback speed, pause/refresh |
| Appearance | Floating effect, mouse glow, theme colour, corner radius, grey text, liquid glass |
| Unified appearance | Full-screen blur, whether chat/new-session follow |
| Surface blur | Independent blur for dialogs/settings/popovers/masks/sidebar |
| Other | Power saving, Now Playing, library/rotation, backup/restore, error log, diagnostics |
| Tests | Renderer source, diagnostics parameters, compatibility switches, developer options |
Advanced URL switches, renderer diagnostics and environment variables are documented under docs/.
Security and privacy
- Wallpaper parsing, transcoding and storage happen locally; nothing is uploaded automatically.
- Web wallpapers run in a sandboxed iframe by default; parent and frame communicate only through
postMessage, with allow-listed operations and origin validation. - Image/web URLs are restricted to allowed protocols/targets; scene renderer URLs accept only loopback/same-host/explicit allow-listed origins, and refused targets fall back with a ledger entry.
- Custom folders reject path traversal, absolute paths and sensitive directories;
/rawserves only registered container entries. - System media commands are passed as argv arrays, never through a shell.
- Diagnostics and error logs stay local. Exports support sanitized and full modes.
Compatibility and limits
- Browsers: Chrome / Edge (recommended), Firefox. Environments without WebGL 2 fall back to a static frame with an explicit message.
- DSH Mobile: the mobile shell's sidebar drawer, blur strength and slow first-frame path are adapted; desktop behaviour stays unchanged.
- DSH Desktop: can be installed through the desktop profile; if the host page is
file://, the client resolveshttp://dsh.internalfollowing DSH's convention. - Windows: auto-discovers Wallpaper Engine and Steam libraries. Other OSes can point at the Workshop folder manually.
- Not supported:
.exe/ non-media files as wallpapers; exact parity for every WE scene effect; unlimited web-wallpaper interaction (browser sandbox limits apply); downloading paid Wallpaper Engine assets.
Troubleshooting
- No wallpaper: check the master switch and source; restart
dsh webandCtrl+F5; check the browser console. - Scene wallpaper is black/static: check Tests → Renderer source uses the bundled renderer; no-WebGL environments show a static-frame notice.
- Floating Island does nothing: make sure Appearance → Floating effect is on; narrow windows/mobile layouts may switch automatically and recalibrate when the width is restored.
- Mobile sidebar is see-through: fully quit and reopen the DSH Mobile app (to refresh the client bundle); if it persists, attach device/DSH Mobile versions.
- Exporting logs: each error block has Export sanitized log and Export full log on its right; the footer has Clear log and Close.
More: DIAGNOSTICS, WALLPAPER-LIFECYCLE, WEB-WALLPAPER and NOW-PLAYING-DSH under docs/.
Development and gates
# quick checks
node tools/integrity-check.mjs
node tools/secret-scan-test.mjs
node tools/style-scope-guard.mjs
# full 12-step gate (some steps need headless Firefox / local :3080)
bash tools/check.sh
Build notes:
lib/client.jsis the single client file served by the host;lib/now-playing.js,lib/now-playing-math.jsandlib/audio-bus.jsare inlined by build scripts into generated regions — do not hand-edit those regions;renderer/**is the bundled scene renderer (GPL-3.0-or-later); the plugin talks to it only over iframe + postMessage and never imports its source;dist/,tools/anddocs/do not enter the npm package.
File structure
dsh-mpkg-wallpaper/
├── package.json # npm metadata + dsh plugin declaration + files allow-list
├── cordis.patch.yml # dsh install declaration
├── LICENSE # MIT (plugin body)
├── LICENSE-render # GPLv3 (renderer/**)
├── NOTICE # dual-license scope / attribution / modification notices
├── LICENSES/ # MIT.txt, GPL-3.0-or-later.txt
├── lib/ # host + client (client.js is served as one file)
├── renderer/ # bundled WEwebLoader scene renderer (GPL-3.0-or-later)
├── tools/ # gates/tests/build scripts (not published)
├── docs/ # engineering and operations docs (not published)
└── dist/ # single-file bundle output (not committed)
License
This repository contains two independently licensed parts:
| Part | License | Full text |
|---|---|---|
Plugin body lib/**, icon, README, NOTICE, THIRD-PARTY, etc. |
MIT | LICENSE, LICENSES/MIT.txt |
Bundled renderer renderer/** |
GPL-3.0-or-later | LICENSE-render, renderer/LICENSE, LICENSES/GPL-3.0-or-later.txt |
Directory boundaries, redistribution notes and the GPLv3 §5a modification notice are in NOTICE. Third-party attribution is in THIRD-PARTY.md and renderer/THIRD-PARTY.md.
The license field in package.json is SEE LICENSE IN NOTICE.
Feedback
Please include:
- the original
.mpkgor Workshop folder (enough to reproduce); - one Other → One-click diagnostics result;
- browser console errors;
- DSH version, OS and browser/client environment.
Repository: https://github.com/XHR666/dsh-mpkg-wallpaper npm: https://www.npmjs.com/package/dsh-mpkg-wallpaper
Links
More in this category
zhu1090093659/dsh-web#packages/dsh-task-board★ 10406
Task board for the dsh web GUI: a sidebar multi-column kanban whose cards run in real DSH agent sessions and can also be scheduled with cron expressions, executed host-side even with the browser closed.
zhu1090093659/dsh-web#packages/dsh-web-all★ 10406
Plugin and skin collection for the DSH Web UI: task board, Git graph, right-side panel, remote mobile UI, pet, live token stats, and a skin center.
ccch1mneyyy/dsh-TUI★ 7675
Claude Code-style full-screen terminal UI: pixel-whale header, live status line, and streaming thought expansion.
MeteorNOX/DeepSeek-Balance-Whale-Widget★ 7201
A fixed-corner whale widget for the DSH web GUI — balance, today's usage and per-turn cost with peak/off-peak pricing, editable balance-alert and daily-budget bubbles, a module-based custom bubble queue with A/B weighted choices and random lines or images, 30+ vendor templates (OpenAI, OpenRouter, Kimi, SiliconFlow, Ark, Zhipu, MiniMax and more) with per-model balance and subscription quota, plus task-end sound, imported audio, custom roles and a resource manager. Local-only, no telemetry.
omdsh-dev/DSH-better-sidebar★ 5142
Full sidebar workbench with file rendering and editing, terminal, Git, and subagents; third-party plugins can register new tabs.
omdsh-dev/dsh-genui★ 988
Interactive UI components rendered inline in replies: layout, charts, forms, quizzes, mermaid, 3D scenes, and an action event loop back to the model.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.