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