dsh-beauty-persist

Persist dsh-dream-skin / dsh-liquid-glass wallpaper & theme across DSH Desktop restarts.

Why

The DSH Desktop shell launches its web carrier with an OS-assigned random port (--port 0), so the browser origin changes on every restart. Browser localStorage is partitioned per origin — visual state like a wallpaper image (stored by dream-skin / liquid-glass in localStorage) disappears after each restart, even though it was never deleted.

dsh-beauty-persist moves that visual state into a server-side JSON file that is independent of the port. It restores the state on every page load and pushes changes back to the server when you tweak the settings in the UI.

What it does

• Host half (lib/index.js)
  • Serves GET /beauty-persist/state (current persisted state) and POST /beauty-persist/state (replace persisted state).
  • Serves GET /beauty-persist/wallpaper.gif (the stored GIF wallpaper) and POST /beauty-persist/wallpaper.gif (upload a new GIF wallpaper).
  • Injects the persisted state into the index.html response as window.__DSH_BEAUTY_PERSIST_STATE__, before the boot manifest, so the browser half restores synchronously ahead of dream-skin/liquid-glass initialization.
• Browser half (lib/client.js)
  • Restores every dsh-dream-skin:* / dsh-liquid-glass:* localStorage key from the server-injected state on page load.
  • Hooks Storage.prototype.setItem / removeItem and mirrors any later changes back to the server (debounced), so your wallpaper/skin choices keep persisting without you doing anything extra.
  • Exposes uploadGifWallpaper(gif) to set an animated GIF wallpaper.

State is stored at ~/.dsh/beauty-persist-state.json; the GIF wallpaper file lives at ~/.dsh/beauty-persist-wallpaper.gif.

Install

Works with any profile that already runs dsh-dream-skin and/or dsh-liquid-glass (typically the desktop profile used by DSH Desktop).

cd ~/.dsh/profiles/desktop

# add the dependency (adjust the repo URL / tag to what you installed)
pnpm add dsh-beauty-persist@github:<owner>/<repo>

# register the bundle in dsh.profile.bundles of package.json
#   "dsh-beauty-persist",

Then restart DSH Desktop so the new bundle is loaded.

Usage

Nothing to configure. Once installed:

1. Restart DSH Desktop (required for the bundle to load).
2. In the GUI open Settings → Theme / 外观 and pick your wallpaper / skin as usual.
3. The choice is now persisted server-side — it survives restarts, port changes, browser cache clears, and even switching browsers.

If you already have a wallpaper set in a previous session's localStorage (now orphaned under an old port), either re-pick it once after installing, or seed the server state manually:

# example: put a data-URL or URL into the state file
echo '{"dsh-dream-skin:wallpaper":"https://example.com/wall.jpg"}' \
  > ~/.dsh/beauty-persist-state.json

Animated GIF wallpaper

dream-skin's "pick image" flow re-encodes through a canvas and flattens animated GIFs into a static JPEG. To use an animated GIF instead, upload it to this plugin — the browser renders the GIF natively (it plays), and the file is stored server-side so it survives restarts.

In the GUI (no command line): after installing, open Settings → Theme / 外观 — a "GIF 壁纸上传（动图）" row appears in the appearance section. Click 选择 GIF…, pick a local .gif, and it is uploaded, activated and persisted. Refresh the GUI to see the animation.

From the command line:

# from this repo — the script auto-discovers the DSH Desktop GUI port
node scripts/set-gif-wallpaper.mjs "C:\path\to\my-wallpaper.gif"

# or pass the base URL explicitly if your GUI is served elsewhere
node scripts/set-gif-wallpaper.mjs "C:\path\to\my-wallpaper.gif" http://127.0.0.1:8080

After upload, refresh the GUI (or restart DSH Desktop): the GIF plays as the wallpaper and persists across restarts. Swap it any time by re-running the script with a different GIF.

MP4 video wallpaper

CSS background-image cannot play video, so MP4 wallpapers are rendered by this plugin as a full-viewport <video> layer (muted, looping, object-fit cover).

In the GUI: the "MP4 视频壁纸（动效）" row (also under Settings → Theme / 外观) lets you pick a local .mp4 and activate it, or remove the video wallpaper.

From the command line:

node scripts/set-mp4-wallpaper.mjs "C:\path\to\my-wallpaper.mp4"
# optional explicit base URL:
node scripts/set-mp4-wallpaper.mjs "C:\path\to\my-wallpaper.mp4" http://127.0.0.1:8080

The MP4 is stored at ~/.dsh/beauty-persist-wallpaper.mp4 (up to 50 MB) and persists across restarts.

🎨 Skin center (asset library)

Build your own wallpaper library: upload images / GIFs / MP4s once, then switch between them anytime with one click — everything is stored server-side and survives restarts.

In the GUI: the "🎨 皮肤中心" row (under Settings → Theme / 外观) gives you:

• 上传素材… — pick a local image / GIF / MP4 to add it to the library (stored at ~/.dsh/beauty-persist-assets/, up to 50 MB each).
• A thumbnail grid of your assets — click any thumbnail to apply it as the wallpaper right away (images/GIFs render as a background layer, GIFs animate natively; MP4s render as a looping video layer).
• ✕ on a thumbnail deletes the asset from the library.

The currently applied asset is remembered in the server-side state, so after a restart the same wallpaper comes back automatically.

Requirements

• @deepseek-ai/dsh-client-runtime, @deepseek-ai/dsh-client-locale, @deepseek-ai/dsh-client-ui-theme (the standard web client stack; present in every shipped Web composition).
• Node >= 18 for the host half.

License

MIT