dsh-beauty-persist

Readme

# dsh-beauty-persist

> Persist [dsh-dream-skin](https://github.com/RevolutionLA/dsh-dream-skin) / [dsh-liquid-glass](https://github.com/Ultronen/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).

```sh
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:

```sh
# 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:**

```sh
# 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:**

```sh
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