dsh-any-background 0.1.3 → 0.1.5

package/README.md

@@ -16,7 +16,7 @@ A **DeepSeek Harness** appearance plugin that lets you fully customize the Web U
 - **Background Wallpaper** — Choose any image as your wallpaper. Drag to pan, scroll to zoom inside a viewport-proportional editor. What you see is what you get.
 - **Opacity Controls** — Separate sliders for main interface background opacity, settings panel opacity, and wallpaper opacity.
 - **Blur Effect** — Adjustable wallpaper blur (0–60 px) for a frosted-glass look.
-- **Persistent** — All settings (color, wallpaper, opacity, blur, editor position) are saved to `localStorage` and restored on next launch.
+- **Persistent** — All settings (color, wallpaper, opacity, blur, editor position) are stored on the **filesystem** under `~/.dsh/.dsh-any-background-data/` via the node half, and restored on next launch. No more `localStorage` quota worries.
 - **Bilingual** — Full Chinese / English UI with automatic locale detection.
 - **Theme Watchdog** — A background watchdog re-asserts the custom theme if the host resets it, so your pick never silently disappears.
 
@@ -29,7 +29,7 @@ dsh-any-background/
 ├── cordis.yml            # Patch overlay for dev usage (pnpm dsh web --patch)
 ├── tsdown.config.ts      # Build config: node-half (ESM) + client-half (CJS browser bundle)
 ├── src/
-│   ├── index.ts          # Node half — empty shell for Cordis loader mount
+│   ├── index.ts          # Node half — file-backed persistence (RPC file store)
 │   ├── invariant.ts      # Invariant companion (registers package ownership)
 │   └── client/
 │       └── index.tsx     # Browser half — ALL UI logic lives here
@@ -45,7 +45,24 @@ dsh-any-background/
 
 ## Implementation
 
-The plugin is a **pure client-side** Cordis plugin. The node half is an empty shell; all behavior lives in `src/client/index.tsx`.
+The plugin is a Cordis plugin split into two halves:
+
+- **Node half** (`src/index.ts`) — owns file-backed persistence. It manages the `.dsh-any-background-data/` store under the DSH data home (`~/.dsh/`) and exposes a small RPC surface over the shared `/api` channel.
+- **Browser half** (`src/client/index.tsx`) — all UI logic lives here. The browser cannot touch the filesystem, so it reads/writes the store through the node half's RPC endpoints.
+
+### Persistence
+
+Since the plugin surfaces in the browser, persisted data is stored on disk by the **node half**:
+
+```
+~/.dsh/.dsh-any-background-data/
+├── theme-config.json   # color, main/settings/wallpaper opacity, blur, bg edit state
+└── wallpaper.jpg       # the chosen background image (deleted when removed)
+```
+
+- On startup the client calls `read`, which returns the config and (if present) the wallpaper as a data URL.
+- Every setting change is written back synchronously to `theme-config.json`; changing the wallpaper writes `wallpaper.jpg`, removing it deletes the file.
+- The store is created automatically if missing; a missing or malformed config falls back to defaults (with a warning), and all writes are error-guarded to avoid data loss.
 
 ### Architecture
 
@@ -93,7 +110,7 @@ The plugin is a **pure client-side** Cordis plugin. The node half is an empty sh
 ### Background Wallpaper
 
 - A `<div>` with `position:fixed; z-index:-1` is prepended to `<body>`.
-- Image is compressed via Canvas API (max 1600px side, JPEG quality 0.75) and stored as base64 in `localStorage`.
+- Image is compressed via Canvas API (max 1600px side, JPEG quality 0.75); the node half writes it to `~/.dsh/.dsh-any-background-data/wallpaper.jpg`, and the client keeps the data URL in memory for display.
 - The editor modal shows a viewport-proportional rectangle; drag to pan, scroll to zoom (0.1×–10×).
 - Committed position is stored as fractional center coordinates + natural image size, so the layout survives viewport changes.
 - Wallpaper opacity is applied directly to the `<div>` element; background color opacity is applied via inline token overrides.
@@ -117,13 +134,13 @@ The plugin is a **pure client-side** Cordis plugin. The node half is an empty sh
 
 ### Opacity System
 
-Three independent opacity layers, each with its own slider and `localStorage` key:
+Three independent opacity layers, each with its own slider and a persisted config field:
 
-| Layer | localStorage key | Default | Mechanism |
-|-------|-----------------|---------|-----------|
-| Main interface | `dsh-any-background:opacity` | 85% | Inline CSS variable on `<body>` |
-| Settings panel | `dsh-any-background:settings-opacity` | 100% | CSS variable on `<html>` via `[aria-modal]` selector |
-| Wallpaper | `dsh-any-background:wallpaper-opacity` | 100% | Direct `style.opacity` on wallpaper `<div>` |
+| Layer | Config field | Default | Mechanism |
+|-------|--------------|---------|-----------|
+| Main interface | `opacity` | 85% | Inline CSS variable on `<body>` |
+| Settings panel | `settingsOpacity` | 100% | CSS variable on `<html>` via `[aria-modal]` selector |
+| Wallpaper | `wallpaperOpacity` | 100% | Direct `style.opacity` on wallpaper `<div>` |
 
 #### Settings Opacity
 
@@ -203,24 +220,33 @@ editing `src/`, run the bundle script (needs Node + pnpm):
 git clone https://github.com/Tkingxiao/dsh-any-background.git
 cd dsh-any-background
 
-# 2. Install the build tool
+# 2. Install the build tool (also pulls the @deepseek-ai/dsh-home-paths runtime dep)
 pnpm install
 
 # 3. Rebuild lib/
 pnpm run bundle
 
-# 4. Install the plugin into the web profile (from the local checkout)
-dsh plugin --profile web add -w .
+# 4. Install the plugin into the web profile from the local checkout
+#    (`dsh plugin add` wraps `pnpm add <dir>`, so point it at this directory)
+dsh plugin --profile web add .
 
 # 5. Launch
 dsh web
 ```
 
+## Compatibility
+
+The plugin works on both the **Web UI** and the **desktop client**:
+
+- **[`dsh web`](https://github.com/deepseek-ai/deepseek-harness)** — Web profile, full support.
+- **[deepseek-harness-desktop](https://github.com/anywhere-labs/deepseek-harness-desktop)** — supported, but there is a known Electron packaging issue: the **left sidebar and the center area opacity are inverted** (the sidebar looks more transparent than the center and vice versa). This is a client-side packaging bug, not a plugin bug — we are waiting for the desktop client to be updated to fix it.
+
 ## Dependencies
 
 | Package | Purpose |
 |---------|---------|
 | `@deepseek-ai/cordis` | Plugin framework (Cordis) |
+| `@deepseek-ai/dsh-home-paths` | Resolve the DSH data home for the persistence store |
 | `@deepseek-ai/dsh-client-runtime` | Client runtime + `defineStore` |
 | `@deepseek-ai/dsh-client-locale` | i18n (Chinese/English) |
 | `@deepseek-ai/dsh-client-ui-theme` | Theme service (register/setTheme/overrideTokens) |

package/README.zh.md

@@ -16,7 +16,7 @@
 - **背景壁纸** — 选择任意图片作为壁纸。在视口比例的编辑器中拖动平移、滚轮缩放，所见即所得。
 - **透明度控制** — 主界面背景透明度、设置面板透明度、壁纸透明度各自独立滑块控制。
 - **模糊效果** — 可调壁纸模糊（0–60 px），打造毛玻璃质感。
-- **持久化存储** — 所有设置（颜色、壁纸、透明度、模糊、编辑器位置）保存到 `localStorage`，下次启动自动恢复。
+- **持久化存储** — 所有设置（颜色、壁纸、透明度、模糊、编辑器位置）由 Node 端保存到 **文件系统** 的 `~/.dsh/.dsh-any-background-data/`，下次启动自动恢复。不再受 `localStorage` 容量限制。
 - **中英双语** — 完整的中英文界面，自动跟随语言设置。
 - **主题守护** — 后台看门狗定期重新激活自定义主题，即使宿主重置也不会丢失你的选择。
 
@@ -29,7 +29,7 @@ dsh-any-background/
 ├── cordis.yml            # 开发用补丁覆盖层（pnpm dsh web --patch）
 ├── tsdown.config.ts      # 构建配置：Node 端（ESM）+ 客户端（CJS 浏览器包）
 ├── src/
-│   ├── index.ts          # Node 端 — 空壳，供 Cordis 加载器挂载
+│   ├── index.ts          # Node 端 — 文件持久化（RPC 文件存储）
 │   ├── invariant.ts      # 不变量 companion（注册包所有权）
 │   └── client/
 │       └── index.tsx     # 浏览器端 — 所有 UI 逻辑都在这里
@@ -45,7 +45,24 @@ dsh-any-background/
 
 ## 实现原理
 
-本插件是一个**纯客户端** Cordis 插件。Node 端是空壳，所有行为都在 `src/client/index.tsx` 中实现。
+本插件是一个 Cordis 插件，分为两个部分：
+
+- **Node 端**（`src/index.ts`）— 负责文件持久化。管理 DSH 数据主目录（`~/.dsh/`）下的 `.dsh-any-background-data/` 存储，并在共享 `/api` 通道上暴露一组小的 RPC 接口。
+- **浏览器端**（`src/client/index.tsx`）— 所有 UI 逻辑都在这里。浏览器无法直接读写文件系统，因此通过 Node 端的 RPC 接口读写存储。
+
+### 持久化
+
+由于插件运行在浏览器中，持久化数据由 **Node 端** 写入磁盘：
+
+```
+~/.dsh/.dsh-any-background-data/
+├── theme-config.json   # 主题色、主界面/设置面板/壁纸透明度、模糊、壁纸编辑状态
+└── wallpaper.jpg       # 选中的背景图片（移除时删除）
+```
+
+- 启动时客户端调用 `read`，返回配置以及（如果存在）壁纸的 data URL。
+- 每次设置变更都会同步写回 `theme-config.json`；更换壁纸写入 `wallpaper.jpg`，移除壁纸则删除文件。
+- 存储目录不存在时会自动创建；配置缺失或损坏时回退默认值（并记录警告），所有写入都有错误保护以避免数据丢失。
 
 ### 架构
 
@@ -93,7 +110,7 @@ dsh-any-background/
 ### 背景壁纸
 
 - 一个 `position:fixed; z-index:-1` 的 `<div>` 被插入到 `<body>` 最前面。
-- 图片通过 Canvas API 压缩（最大边 1600px，JPEG 质量 0.75），以 base64 存入 `localStorage`。
+- 图片通过 Canvas API 压缩（最大边 1600px，JPEG 质量 0.75）；Node 端写入 `~/.dsh/.dsh-any-background-data/wallpaper.jpg`，客户端在内存中保留 data URL 用于显示。
 - 编辑器弹窗显示视口比例的矩形区域；拖动平移，滚轮缩放（0.1×–10×）。
 - 提交的位置以分数中心坐标 + 原始图片尺寸存储，布局在视口变化时保持一致。
 - 壁纸透明度直接作用于 `<div>` 元素；背景色透明度通过内联令牌覆盖实现。
@@ -117,13 +134,13 @@ dsh-any-background/
 
 ### 透明度体系
 
-三个独立的透明度层，各有独立滑块和 `localStorage` 键：
+三个独立的透明度层，各有独立滑块和一个持久化的配置字段：
 
-| 层 | localStorage 键 | 默认值 | 实现方式 |
-|----|-----------------|--------|---------|
-| 主界面 | `dsh-any-background:opacity` | 85% | `<body>` 上的内联 CSS 变量 |
-| 设置面板 | `dsh-any-background:settings-opacity` | 100% | `<html>` 上的 CSS 变量，通过 `[aria-modal]` 选择器定位 |
-| 壁纸 | `dsh-any-background:wallpaper-opacity` | 100% | 壁纸 `<div>` 上的 `style.opacity` |
+| 层 | 配置字段 | 默认值 | 实现方式 |
+|----|----------|--------|---------|
+| 主界面 | `opacity` | 85% | `<body>` 上的内联 CSS 变量 |
+| 设置面板 | `settingsOpacity` | 100% | `<html>` 上的 CSS 变量，通过 `[aria-modal]` 选择器定位 |
+| 壁纸 | `wallpaperOpacity` | 100% | 壁纸 `<div>` 上的 `style.opacity` |
 
 #### 设置透明度
 
@@ -202,24 +219,33 @@ npx @deepseek-ai/dsh web
 git clone https://github.com/Tkingxiao/dsh-any-background.git
 cd dsh-any-background
 
-# 2. 安装构建工具
+# 2. 安装构建工具（同时拉取 @deepseek-ai/dsh-home-paths 运行时依赖）
 pnpm install
 
 # 3. 重新构建 lib/
 pnpm run bundle
 
 # 4. 从本地安装到 web profile
-dsh plugin --profile web add -w .
+#    （`dsh plugin add` 是 `pnpm add <dir>` 的封装，传入本目录即可）
+dsh plugin --profile web add .
 
 # 5. 启动
 dsh web
 ```
 
+## 兼容性
+
+插件同时支持 **Web 界面** 和 **桌面客户端**：
+
+- **[`dsh web`](https://github.com/deepseek-ai/deepseek-harness)** — Web profile，完整支持。
+- **[deepseek-harness-desktop](https://github.com/anywhere-labs/deepseek-harness-desktop)** — 已支持，但存在一个已知的 Electron 打包问题：**左侧边栏与主区域的透明度相反**（侧边栏看起来比主区域更透明，反之亦然）。这是客户端侧打包问题，并非插件缺陷 —— 我们正在等待桌面客户端更新修复。
+
 ## 依赖
 
 | 包名 | 用途 |
 |------|------|
 | `@deepseek-ai/cordis` | 插件框架（Cordis） |
+| `@deepseek-ai/dsh-home-paths` | 解析 DSH 数据主目录，用于持久化存储 |
 | `@deepseek-ai/dsh-client-runtime` | 客户端运行时 + `defineStore` |
 | `@deepseek-ai/dsh-client-locale` | 国际化（中/英） |
 | `@deepseek-ai/dsh-client-ui-theme` | 主题服务（register/setTheme/overrideTokens） |