dsh-any-background 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tkingxiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# dsh-any-background
+
+<a href="https://github.com/Tkingxiao/dsh-any-background" target="_blank">
+  <img src="https://img.shields.io/github/stars/Tkingxiao/dsh-any-background?style=social" alt="GitHub stars" />
+</a>
+
+English | [中文](README.zh.md)
+
+A **DeepSeek Harness** appearance plugin that lets you fully customize the Web UI with a custom theme color, background wallpaper, and fine-grained opacity controls.
+
+<p align="center">
+  <a href="https://star-history.com/#/Tkingxiao/dsh-any-background" target="_blank">
+    <img src="https://api.star-history.com/svg?repos=Tkingxiao/dsh-any-background&type=Date" alt="Star History Chart" width="600" />
+  </a>
+</p>
+
+---
+
+## Features
+
+- **PS-style Color Wheel** — Pick hue on the ring, adjust saturation & lightness in the inscribed square. Generates a full set of 30+ CSS design tokens in real time and applies them instantly.
+- **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.
+- **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.
+
+## Project Structure
+
+```
+dsh-any-background/
+├── package.json          # Package metadata, dsh.client declaration, dependencies
+├── cordis.patch.yml      # Bundle patch layer (inserted into profile composition)
+├── 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
+│   ├── invariant.ts      # Invariant companion (registers package ownership)
+│   └── client/
+│       └── index.tsx     # Browser half — ALL UI logic lives here
+├── lib/                  # Built output, committed so installs need no build step
+│   ├── index.js          # Node entry
+│   ├── invariant.js      # Invariant entry
+│   ├── client.js         # Browser bundle (wrapped for __ModuleLoader__)
+│   └── client.js.map     # Source map
+├── README.md             # This file (English)
+└── README.zh.md          # 中文版
+```
+
+## 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`.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  apply(ctx)  —  Plugin entry point                      │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  1. Restore saved color → registerCustom() → setTheme   │
+│  2. Inject gradient <style> into <head>                 │
+│  3. Create state store (defineStore)                    │
+│  4. applyWp() → wallpaper + token overrides             │
+│  5. Listen theme/change → re-apply                      │
+│  6. ResizeObserver → viewport-aware re-positioning      │
+│  7. Locale registration (zh/en)                         │
+│  8. Settings section injection (ThemeSection)           │
+│  9. Deferred boot restore (300ms, 1500ms)               │
+│ 10. Theme watchdog (1s interval)                        │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Color Wheel
+
+- Single `<canvas>` element: hue ring (360° segments) + inscribed SL square (HSV S-V plane).
+- `hitTest()` determines whether a click lands on the ring (hue) or square (saturation/lightness).
+- HSV values from the canvas are converted to HSL via `hsvToHsl()` before passing to `genTokens()`.
+- `genTokens()` generates 30+ CSS custom properties (`--dsw-alias-*`) for the picked color, choosing dark or light scheme based on lightness.
+- The full token set is written as inline styles on `<body>`, so the theme color never depends on the theme service's timing.
+
+### 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`.
+- 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.
+
+### Opacity System
+
+Three independent opacity layers, each with its own slider and `localStorage` key:
+
+| 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>` |
+
+## Installation
+
+### Method 1: npm install (Recommended)
+
+Install the plugin directly from GitHub into your Web profile:
+
+```sh
+dsh plugin --profile web add github:Tkingxiao/dsh-any-background
+```
+
+Then launch the Web UI:
+
+```sh
+dsh web
+```
+
+The plugin will appear as a **"Theme"** section in the Settings panel.
+
+### Method 2: npx (No Global Install)
+
+If you don't have `dsh` installed globally, use `npx`:
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add github:Tkingxiao/dsh-any-background
+```
+
+Then launch:
+
+```sh
+npx @deepseek-ai/dsh web
+```
+
+### Method 3: Local Build (Development)
+
+The `lib/` directory is committed, so installs need no build step. To rebuild after
+editing `src/`, run the bundle script (needs Node + pnpm):
+
+```sh
+# 1. Clone this repo
+git clone https://github.com/Tkingxiao/dsh-any-background.git
+cd dsh-any-background
+
+# 2. Install the build tool
+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 .
+
+# 5. Launch
+dsh web
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@deepseek-ai/cordis` | Plugin framework (Cordis) |
+| `@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) |
+| `@deepseek-ai/dsh-invariants` | Package invariant companion |
+| `react` ^18.2.0 | UI rendering |
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,169 @@
+# dsh-any-background
+
+<a href="https://github.com/Tkingxiao/dsh-any-background" target="_blank">
+  <img src="https://img.shields.io/github/stars/Tkingxiao/dsh-any-background?style=social" alt="GitHub stars" />
+</a>
+
+[English](README.md) | 中文
+
+一个 **DeepSeek Harness** 外观插件，让你完全自定义 Web 端的主题色、背景壁纸和透明度控制。
+
+<p align="center">
+  <a href="https://star-history.com/#/Tkingxiao/dsh-any-background" target="_blank">
+    <img src="https://api.star-history.com/svg?repos=Tkingxiao/dsh-any-background&type=Date" alt="Star 历史趋势图" width="600" />
+  </a>
+</p>
+
+---
+
+## 功能特性
+
+- **PS 风格色轮** — 在色相环上选取色相，在内嵌方形中调整饱和度与明度。实时生成 30+ 个 CSS 设计令牌并立即生效。
+- **背景壁纸** — 选择任意图片作为壁纸。在视口比例的编辑器中拖动平移、滚轮缩放，所见即所得。
+- **透明度控制** — 主界面背景透明度、设置面板透明度、壁纸透明度各自独立滑块控制。
+- **模糊效果** — 可调壁纸模糊（0–60 px），打造毛玻璃质感。
+- **持久化存储** — 所有设置（颜色、壁纸、透明度、模糊、编辑器位置）保存到 `localStorage`，下次启动自动恢复。
+- **中英双语** — 完整的中英文界面，自动跟随语言设置。
+- **主题守护** — 后台看门狗定期重新激活自定义主题，即使宿主重置也不会丢失你的选择。
+
+## 项目结构
+
+```
+dsh-any-background/
+├── package.json          # 包元数据、dsh.client 声明、依赖
+├── cordis.patch.yml      # 捆绑补丁层（插入到 profile 组合配置中）
+├── cordis.yml            # 开发用补丁覆盖层（pnpm dsh web --patch）
+├── tsdown.config.ts      # 构建配置：Node 端（ESM）+ 客户端（CJS 浏览器包）
+├── src/
+│   ├── index.ts          # Node 端 — 空壳，供 Cordis 加载器挂载
+│   ├── invariant.ts      # 不变量 companion（注册包所有权）
+│   └── client/
+│       └── index.tsx     # 浏览器端 — 所有 UI 逻辑都在这里
+├── lib/                  # 构建产物（已提交，安装无需构建步骤）
+│   ├── index.js          # Node 入口
+│   ├── invariant.js      # 不变量入口
+│   ├── client.js         # 浏览器包（经 __ModuleLoader__ 包装）
+│   └── client.js.map     # 源码映射
+├── README.md             # 英文版说明
+└── README.zh.md          # 本文件（中文）
+```
+
+## 实现原理
+
+本插件是一个**纯客户端** Cordis 插件。Node 端是空壳，所有行为都在 `src/client/index.tsx` 中实现。
+
+### 架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  apply(ctx)  —  插件入口                                 │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  1. 恢复保存的颜色 → registerCustom() → setTheme        │
+│  2. 注入渐变 <style> 到 <head>                          │
+│  3. 创建状态存储（defineStore）                           │
+│  4. applyWp() → 壁纸 + 令牌覆盖                         │
+│  5. 监听 theme/change → 重新应用                         │
+│  6. ResizeObserver → 视口感知重定位                       │
+│  7. 语言注册（中/英）                                     │
+│  8. 设置面板注入（ThemeSection）                          │
+│  9. 延迟启动恢复（300ms, 1500ms）                         │
+│ 10. 主题守护（1 秒间隔）                                  │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 色轮
+
+- 单个 `<canvas>` 元素：色相环（360° 分段）+ 内嵌 SL 方形（HSV S-V 平面）。
+- `hitTest()` 判断点击落在色相环（色相）还是方形（饱和度/明度）上。
+- 色轮拾取的 HSV 值通过 `hsvToHsl()` 转换为 HSL 后传给 `genTokens()`。
+- `genTokens()` 根据所选颜色生成 30+ 个 CSS 自定义属性（`--dsw-alias-*`），根据明度自动选择深色或浅色方案。
+- 完整令牌集以内联样式写入 `<body>`，主题色完全不依赖主题服务的时序。
+
+### 背景壁纸
+
+- 一个 `position:fixed; z-index:-1` 的 `<div>` 被插入到 `<body>` 最前面。
+- 图片通过 Canvas API 压缩（最大边 1600px，JPEG 质量 0.75），以 base64 存入 `localStorage`。
+- 编辑器弹窗显示视口比例的矩形区域；拖动平移，滚轮缩放（0.1×–10×）。
+- 提交的位置以分数中心坐标 + 原始图片尺寸存储，布局在视口变化时保持一致。
+- 壁纸透明度直接作用于 `<div>` 元素；背景色透明度通过内联令牌覆盖实现。
+
+### 透明度体系
+
+三个独立的透明度层，各有独立滑块和 `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` |
+
+## 安装方式
+
+### 方式一：npm 安装（推荐）
+
+直接从 GitHub 安装插件到 Web profile：
+
+```sh
+dsh plugin --profile web add github:Tkingxiao/dsh-any-background
+```
+
+然后启动 Web UI：
+
+```sh
+dsh web
+```
+
+插件将作为 **"主题"** 分区出现在设置面板中。
+
+### 方式二：npx（无需全局安装）
+
+如果没有全局安装 `dsh`，可以使用 `npx`：
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add github:Tkingxiao/dsh-any-background
+```
+
+然后启动：
+
+```sh
+npx @deepseek-ai/dsh web
+```
+
+### 方式三：本地构建（开发模式）
+
+`lib/` 目录已提交，安装无需构建步骤。若修改了 `src/` 需要重新构建（需 Node + pnpm）：
+
+```sh
+# 1. 克隆本仓库
+git clone https://github.com/Tkingxiao/dsh-any-background.git
+cd dsh-any-background
+
+# 2. 安装构建工具
+pnpm install
+
+# 3. 重新构建 lib/
+pnpm run bundle
+
+# 4. 从本地安装到 web profile
+dsh plugin --profile web add -w .
+
+# 5. 启动
+dsh web
+```
+
+## 依赖
+
+| 包名 | 用途 |
+|------|------|
+| `@deepseek-ai/cordis` | 插件框架（Cordis） |
+| `@deepseek-ai/dsh-client-runtime` | 客户端运行时 + `defineStore` |
+| `@deepseek-ai/dsh-client-locale` | 国际化（中/英） |
+| `@deepseek-ai/dsh-client-ui-theme` | 主题服务（register/setTheme/overrideTokens） |
+| `@deepseek-ai/dsh-invariants` | 包不变量 companion |
+| `react` ^18.2.0 | UI 渲染 |
+
+## 许可证
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Deep Midnight theme plugin: bundle patch layer.
+# When this package is installed into a profile via `dsh plugin add`,
+# this patch is applied as a layer, inserting the theme plugin row
+# into the composed configuration.
+
+- insert:
+    - id: dsh-any-background
+      name: 'dsh-any-background'