dsh-we-wallpaper

Use your local Wallpaper Engine library as the background of the DeepSeek Harness Web GUI — video wallpapers play, web wallpapers render, and scene wallpapers get a one-time high-resolution animated cache from Wallpaper Engine. Hot-pluggable, dependency-free, no dsh source changes.

• Language: 简体中文

Screenshots / 演示

The wallpaper library card and a scene wallpaper applied as the GUI background:

设置卡片与应用到界面背景的场景壁纸：

Features

• Plays the wallpaper as the GUI background
  • video wallpapers play as a looping muted <video> (native resolution)
  • web wallpapers render in a sandboxed, click-through <iframe>
  • image wallpapers display as-is
  • scene wallpapers in animated-first mode are first rendered true fullscreen by Wallpaper Engine (borderless, topmost, native monitor resolution, taskbar hidden for the capture) and recorded through Windows.Graphics.Capture as a 12-second H.264 loop; subsequent loads use the cache and never upscale the 160px Workshop preview
  • HD-static mode and failure fallback still use the dependency-free .pkg / TEX decoder to extract the exact 4K–8K background texture
• A settings card in the official plugin configuration section (设置 → 插件配置): browse the library with live previews, search, one-click apply, and a badge marking the wallpaper currently running on your desktop
• Readability controls: dark scrim, panel translucency (the official surface tokens are re-declared translucent — works in light and dark themes), cover / contain fit, sharpening (SVG convolution filter for fallback preview sources), and an animated first / HD static scene mode
• Resource-conscious playback: the media element is reused while the wallpaper is unchanged — dragging a slider never restarts the video stream or spawns another decode pipeline (a memory-leak crash was fixed here)
• Persistent selection in ~/.dsh/we-wallpaper.json; extracted scene artwork cached in ~/.dsh/we-wallpaper-cache/

Animated cache

• HD recordings live under ~/.dsh/we-wallpaper-cache/hd-video/, keyed by Wallpaper Engine Workshop ID, with JSON metadata used for invalidation.
• This is a persistent, rebuildable cache rather than a disposable temporary file. Source or recorder-version changes regenerate it; deleting it manually is safe.
• First generation foregrounds the Wallpaper Engine scene window for about 15 seconds. Later DSH launches read the cached MP4 and do not record again.

Quick start

git clone https://github.com/pbadgpmeb22791-sketch/dsh-we-wallpaper.git
dsh plugin --profile desktop add "<repository-path>\new"

With dsh-super-injector, point the plugin path to <repository-path>\new as well. The repository root keeps the legacy version for rollback.

Restart (or hot-reload) the dsh host, refresh the GUI page, open 设置 → 插件配置 → 动态壁纸, pick a wallpaper, adjust scrim / translucency to taste.

See docs/INSTALL.md for all install paths (including manual cordis.patch.yml editing and dsh-super-injector) and docs/USAGE.md for every option and the troubleshooting guide.

How it works

Half	File	Role
Host	src/we-scanner.ts	Discovers the WE install (env → Steam registry → libraryfolders.vdf → defaults) and parses every project.json
Host	src/pkg-tex.ts	The WE package decoder: directory table, TEXV/TEXB containers, LZ4, DXT1/3/5, embedded PNG/JPEG, PNG encoding
Host	src/pkg-preview.ts	Extraction cache (~/.dsh/we-wallpaper-cache/)
Host	src/scene-video.ts	Builds/caches the HD H.264 loop through the official CLI + wcap
Host	src/routes.ts	/api/we-wallpaper/* route family — same-origin fenced, traversal-guarded
Host	src/state.ts	Selection persistence (~/.dsh/we-wallpaper.json)
Browser	src/client/layer.ts	The fixed background layer: media per type, token-snapshot translucency, scrim, sharpen
Browser	src/client/WallpaperCard.tsx	The library card (previews, search, apply, options)

HTTP API

Route	Purpose
GET /api/we-wallpaper/list	Wallpaper library (id/title/type/source/desktop-active)
GET/POST /api/we-wallpaper/state	Persisted selection + options
GET /api/we-wallpaper/preview/<id>	The local preview file (GIF/JPG/PNG)
GET /api/we-wallpaper/pkg/<id>	The extracted scene background (PNG/JPEG, cached)
GET /api/we-wallpaper/media/<id>	The main media file (range-capable video streaming)
GET /api/we-wallpaper/web/<id>/<path>	Static files of a web wallpaper
POST /api/we-wallpaper/scene-video/generate/<id>	Generate the first HD animated cache
GET /api/we-wallpaper/scene-video/status/<id>	Read progress / failure status
GET /api/we-wallpaper/scene-video/media/<id>	Range-capable cached H.264 stream

Security notes

• Every route rejects cross-site requests (Sec-Fetch-Site / Origin fence) — a random webpage cannot read your wallpaper library through localhost CSRF
• Wallpaper ids resolve only against the scan map; web-file paths are traversal-guarded
• Web wallpapers run in a sandboxed, click-through iframe — they are still your own local files, treat workshop content with the trust you give it in Wallpaper Engine
• Dynamic scenes are opened only by the locally installed Wallpaper Engine. The bundled recorder is the public-domain wcap binary; its license is included at tools/wcap/LICENSE.

Known limitations

• HD animated caching requires the Windows desktop Harness and a running Wallpaper Engine. The scene window comes to the foreground for roughly 15 seconds on first generation. The 12-second loop may have a visible seam for random/non-periodic scenes. Failures safely fall back to the exact HD still or local preview.
• Static extraction first follows the scene.json → model → material → TEX dependency chain. Size/aspect heuristics are used only when scene relations cannot identify the background, so unknown scenes can still select the wrong texture.
• Audio is muted (browser autoplay policy)
• The translucency remap covers the official --dsw-alias-* tokens; third-party plugins with hardcoded backgrounds may stay opaque

What this update fixes

The legacy version could play video wallpapers directly, but scene wallpapers usually had to upscale an approximately 160px Workshop preview. That preserved motion but looked visibly blurred. v0.3.0 lets Wallpaper Engine render the real scene, then records and caches the final HD output as H.264. This preserves both animation and clarity without attempting to reimplement the complete Wallpaper Engine scene renderer.

When recording is disabled or fails, the built-in static path can still resolve the real background texture from scene packages. Sample 3409595232 selects materials/背景.tex at 3840×2160 instead of the foreground character texture. Unknown or protected packages are not forcibly decrypted; they fail safely and return diagnostics.

Roadmap

Possible follow-ups include configurable capture duration/bitrate, cache-space management and one-click cleanup, loop-seam improvements, and support for more legacy or exotic TEX containers. See docs/SUMMARY.md.

Development

npm install
npm run typecheck   # tsc over host + client programs
npm test            # vitest (pkg decoder, LZ4, DXT, cache, scanner)
npm run build       # lib/index.js (host) + lib/client.js (browser bundle)

Diagnostic scripts live in scripts/ (probe-pkg.mjs, probe-previews.mjs, survey-extract.mjs). Full details in docs/DEVELOPMENT.md.

License

MIT — DXT decoding includes a TypeScript port of the LibSquish-derived MIT code from RePKG (Xalcon @ mmowned.com).