dsh-folia 0.0.0-stage → 1.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 elysia395
+
+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.beginner.md

@@ -0,0 +1,165 @@
+# Wallpaper Engine 插件入门 / Beginner Guide
+
+[中文完整版](README.md) · [English README](README.en.md) · [English below](#english)
+
+> **先分清版本**：本指南对应 [Fish-under-sea 灰测源码](https://github.com/Fish-under-sea/dsh-wallpaper-engine)，不是 npm 上已经发布的版本。当前安装单位是**主包 + 七个子包，共八包**，不再内置 pet。正式项目的数据、发布与贡献记录见 [elysia395 主仓](https://github.com/elysia395/dsh-wallpaper-engine)。
+
+## 中文
+
+### 它能做什么
+
+把 Wallpaper Engine 的场景、网页和视频壁纸放到 DSH 聊天界面背后，再调整玻璃、字体、配色与吉祥物。没有 Wallpaper Engine 也能上传自己的 JPG / PNG / MP4。Application 类型需要运行第三方程序，本插件不支持。
+
+界面美化不向 AI 注册工具或注入提示词，**不额外消耗模型 token**。壁纸保存在本机；运行时下载、仓库统计和主动开启的在线歌词仍会联网。
+
+### 安装前准备
+
+- Windows、macOS 或 Linux 上能正常运行的 DSH。
+- **DSH 0.2 内核**，包括 `0.2.0-rc.1/rc.2`；桌面应用版本号与内核版本号不是一回事。
+- **Node.js >=22.12.0、pnpm 和目标宿主的 DSH CLI**。
+- 目标 DSH 的**数据目录**和 **profile**。网页版通常是 `web`；桌面版为 `desktop`。数据目录从目标应用确认，不要照猜 `~/.dsh`。
+- 下载并解压 [本轮评审分支 `official-pet-bridge-20261020`](https://github.com/Fish-under-sea/dsh-wallpaper-engine/tree/official-pet-bridge-20261020) 的完整源码，不要用 Fork 默认分支代替，也不要只下载主包或某个子目录。
+
+Wallpaper Engine 只用于读取已有壁纸资源，不需要一直在后台运行。macOS 没有其官方客户端，可以用自定义上传或已有 WE 项目目录。
+
+### 第一步：完整安装源码
+
+1. 完全退出目标 DSH 应用，包括托盘进程。
+2. 在解压后的插件目录打开终端，确认这里有 `package.json`。
+3. 把命令里的占位目录换成目标 DSH 的真实数据目录，先预览：
+
+```sh
+node scripts/install-source.mjs --profile web --dsh-home "<目标 DSH 数据目录>" --dry-run
+```
+
+确认目标正确后安装：
+
+```sh
+node scripts/install-source.mjs --profile web --dsh-home "<目标 DSH 数据目录>" --app-closed
+```
+
+**桌面版不能只把 `web` 改成 `desktop` 就使用任意 CLI。** 它必须通过桌面宿主提供的 carrier CLI 管理；独立 npm 安装的 `dsh` 会拒绝桌面 profile。需要指定 CLI 时加 `--dsh-cli "<目标 CLI 的 lib/bin.js 路径>"`。不知道目标目录或 CLI 时，先查看 [完整安装说明](README.md#安装)，不要对猜测路径执行。
+
+脚本会安装依赖、构建客户端并登记全部八条持久链接。完成后重启 DSH。**安装后保留源码目录，不要移动或删除它**；链接仍指向这里。
+
+当前灰测不要使用裸 `github:` 直装、临时子包链接工具，或只执行 npm 包名安装。未来整套八包发布后，npm 命令才可取得相应发行版；今天执行包名安装不会取得未发布改动。
+
+### 第二步：选择壁纸
+
+1. 打开 **设置 → Wallpaper Engine → 壁纸库**，或下拉顶部吉祥物拉绳打开抽屉。
+2. 点「选择壁纸」，在**页内库视图**点选缩略图，不是额外的模态弹窗。
+3. 通过返回退出库视图，按需调整外观与播放。设置即时生效，保存到宿主端。
+
+| 想做什么 | 入口与说明 |
+|---|---|
+| 换壁纸 | 壁纸库 → 选择壁纸 |
+| 上传图片 / 视频 | 壁纸库 → 自定义壁纸；支持 JPG / PNG / MP4 |
+| 清除当前壁纸 | 当前壁纸的关闭 / 清除操作；不删除源文件 |
+| 隐藏不喜欢的项目 | 库视图 → 隐藏；可恢复，不删除工坊文件 |
+| 自动轮播 | 轮播列表 → 新建；至少选择两张可播放壁纸 |
+| 改配色、玻璃或字体 | 外观；侧栏有独立参数，不是所有表面共用一根滑条 |
+| 调亮度、取景、倍速或翻转 | 播放 → 效果 |
+| 换吉祥物 | 系统 → 吉祥物；内置十只，也可导入 |
+| 开会话头像、拖尾或视差 | 扩展；按需启用 |
+| 移动缓存 | 系统 → 高级 → 缓存位置 |
+| 移动自定义上传 | 壁纸库 → 自定义壁纸 → 存储位置 |
+
+控件直接显示当前范围与数值。文字不清楚时先调整暗化、边框与玻璃底色；不要为了透明而让所有表面都不可读。**主题随壁纸默认关闭**，只有主动打开后才会自动切深浅色；本张壁纸下的手动主题选择优先。
+
+### 可选：与官方 dsh-pet 联动
+
+不需要桌宠也能完整使用壁纸。联动另装 [官方 dsh-pet](https://github.com/PC2005-cloud/dsh-pet)，Wallpaper **不捆绑、不自动安装，也不改写它的文件**。
+
+1. 官方版本需提供同页位置 / 播放进度和公开控制接口，不能只看 `0.3.7` 版本号。
+2. 将目标宠物设置为网页显示，并把 Wallpaper 吉祥物设为官方侧栏模式。
+3. 按 **Ctrl+Shift+D** 打开调参面板，刷新并选择实际 petId，再试四条联动逻辑。
+
+同一宠物在网页 / 桌面的动作按官方共享状态同步；联动气泡只在发起网页自绘，不会出现在桌面透明窗口，也不会清除官方气泡。未找到目标时原生侧栏操作仍可使用。位置采用官方原生运动，不保证视频缓冲时逐帧同步。完整官方宠物及桌面演出的真机视觉验收仍待补齐，详见 [联动说明](packages/pet-link/README.md)。
+
+从旧内置版升级时，先退出宿主并停用旧内置行；旧依赖、数据与历史补丁不会自动清理。不要为了联动再次安装旧补丁工具。
+
+### 更新与数据
+
+更新时完全退出宿主，更新**整个源码目录**，重跑原安装命令，再启动 DSH。不要只替换某个生成文件。
+
+一般壁纸设置保存在 `~/.dsh-wallpaper-engine/config.json`；缓存和上传默认也在该数据目录。环境变量可覆盖路径。清理浏览器不会删除这份宿主配置，但**pet 目标选择和运行时调参不全在这个文件里**，需要保留的调参请先导出 JSON。
+
+更改缓存 / 上传目录会迁移已识别的插件文件，不搬走目标文件夹里无关的内容。不要把缓存当成上传原件：缓存可重建，自定义壁纸需要另行备份。
+
+### 常见问题
+
+**安装失败或说找不到子包？**
+核对是否在完整仓库根目录、Node / DSH 版本是否达标、目标 home / profile / CLI 是否一致。重跑完整安装器，不要先往活动 profile 手工塞临时链接。保留脱敏日志，参考 [故障排查](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/docs/TROUBLESHOOTING.md)。
+
+**壁纸库是空的？**
+先检查内容分级 / 类型筛选，再确认 WE 下载过壁纸。Steam 未被识别时，可用 `DSH_WE_STEAM_ROOT` 指向含 `steamapps` 的 Steam 根目录。没有 WE 客户端就用上传，或将自定义存储位置指向已有 WE 项目目录。
+
+**视频黑屏或不播放？**
+先看当前壁纸卡片的错误原因，尝试播放或换片。浏览器无法解码时，使用 H.264 MP4。自上传项目也会受内容分级筛选影响。
+
+**Scene 只有静态图？**
+先等首帧。大场景要传输资源包；渲染失败后会降级为可用的预览图或实时帧。并非每个工坊项目都与原版引擎完全兼容。没有可用画面时会说明原因，不会伪造成功。
+
+**文字不好读 / 想关玻璃？**
+先调暗化、底色与边框。玻璃按表面管理，可在对应设置回退原生；未知插件表面不保证自动兼容，见 [共存说明](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/docs/COEXISTENCE.md)。
+
+**插件会把壁纸上传到网上吗？**
+不会。壁纸在本机读取和保存。不过下载运行时、查询仓库数据，以及开启在线歌词后的曲目信息查询会联网。系统频谱采集的是输出回环，不是麦克风。
+
+### 项目与致谢
+
+- 正式项目、发布和贡献历史：[elysia395/dsh-wallpaper-engine](https://github.com/elysia395/dsh-wallpaper-engine)。
+- 当前灰测维护与集成：**[生鱼 / Fish-under-sea](https://github.com/Fish-under-sea/dsh-wallpaper-engine)**，包括部署闭包、官方 pet 桥接、气泡、排播与调参等本分支工作；尚未发布不等于已经合入主仓。
+- 感谢 **[PC2005-cloud / dsh-pet](https://github.com/PC2005-cloud/dsh-pet)** 的公开接口支持与联动讨论。
+- 感谢 B 站 UP 主 **[ZipZipPipe](https://space.bilibili.com/4168597)** 创作的 **AI 娘二创形象**，为我们的新吉祥物提供形象基础。不是模型厂商官方形象；署名不改变角色与素材的权利归属。
+
+其他贡献者、素材与授权见 [完整致谢](README.md#致谢) 和 [素材来源](assets/readme/SOURCES.md)。npm 包不带 `docs/`，技术文档使用当前源码仓库链接。
+
+## English
+
+This guide covers the **unpublished [Fish-under-sea source branch](https://github.com/Fish-under-sea/dsh-wallpaper-engine)**. The official upstream's releases and npm package are separate. The current source suite is **one main package plus seven subpackages**, with no bundled pet.
+
+### Prepare and install
+
+You need a working **DSH 0.2 kernel** (including `0.2.0-rc.1/rc.2`), **Node.js >=22.12.0**, pnpm, the target host's CLI, and its actual data-directory / profile identifiers. Wallpaper Engine is optional if you use custom images / videos. Application wallpapers are unsupported.
+
+1. Download and extract the complete [review branch `official-pet-bridge-20261020`](https://github.com/Fish-under-sea/dsh-wallpaper-engine/tree/official-pet-bridge-20261020), not the fork's default branch.
+2. Fully close the target DSH host. Open a terminal in the folder containing `package.json`.
+3. Replace the placeholder with that host's actual data directory, inspect the plan, then install:
+
+```sh
+node scripts/install-source.mjs --profile web --dsh-home "<target DSH data directory>" --dry-run
+node scripts/install-source.mjs --profile web --dsh-home "<target DSH data directory>" --app-closed
+```
+
+Desktop profiles require `--profile desktop` **and the desktop carrier CLI**. A standalone npm `dsh` CLI refuses desktop management. Pass `--dsh-cli "<target CLI lib/bin.js>"` when needed; do not guess the data directory. See [installation details](README.en.md#install).
+
+The installer builds clients and registers all eight persistent links. Restart DSH afterward. **Keep the source directory in place.** For updates, close DSH, update the whole checkout and rerun the same command. A raw `github:` install, temporary links or installing only the main package does not deploy this branch. npm-name installation applies only after the complete release set is published.
+
+### Choose and adjust a wallpaper
+
+Open **Settings → Wallpaper Engine → Library**, or pull the mascot cord. Choose a thumbnail in the **in-panel library**, not a modal dialog. Use Appearance for glass / fonts / colors, Playback for filters / speed / framing, System for mascots / cache paths, and Extensions for avatars / effects / parallax.
+
+Use JPG / PNG / MP4 uploads without Wallpaper Engine. macOS has no official WE client; existing project directories can also be used. Scene compatibility depends on assets and WebGL; a preview may be shown while preparing or after rendering failure. Rotation needs at least two playable candidates. Hiding a library item does not delete its source.
+
+**Theme-following is off by default.** Readability matters more than maximum transparency. Glass uses per-surface fallback rather than guaranteed compatibility with every third-party skin. System audio capture is output loopback, not the microphone. Online lyrics are opt-in and may send track information to LRCLIB.
+
+### Optional official pet integration
+
+Install official [dsh-pet](https://github.com/PC2005-cloud/dsh-pet) separately, with same-page pose / playback-progress services and public control APIs. Version `0.3.7` alone does not identify those capabilities. Set the target to web display and Wallpaper's mascot to official-sidebar mode; open **Ctrl+Shift+D** to choose the actual petId and try the four routines.
+
+The bridge does not modify official files. Pet actions follow the official shared state across displays; bridge bubbles appear **only in the initiating page** and never clear official bubbles. Missing targets fall back to the ordinary sidebar action. Native motion is not guaranteed to follow buffered video frame by frame. Full official-renderer and desktop visual acceptance is still outstanding. See the [integration guide](packages/pet-link/README.md).
+
+Before upgrading a former bundled-pet setup, close DSH and disable its old bundled row. Old dependencies, data and patches are not automatically removed.
+
+### Settings and troubleshooting
+
+General wallpaper settings persist in `~/.dsh-wallpaper-engine/config.json`. Environment variables may override paths. Pet selection and runtime tuning have a separate lifecycle: export tuning JSON before refresh. Cache files can be regenerated; uploaded originals need their own backups.
+
+For installation errors, verify the complete checkout, supported versions, and exact home / profile / CLI. For an empty library, check filters and Steam detection; `DSH_WE_STEAM_ROOT` points at the Steam root containing `steamapps`. For decoding errors, try H.264 MP4. See [troubleshooting](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/docs/TROUBLESHOOTING.md) and the [English README](README.en.md).
+
+Wallpapers stay local, but runtime downloads, repository statistics and opt-in lyric queries access external services. The plugin registers no model tools or prompt text, so it adds no model token overhead.
+
+### Credits
+
+Official project and history: [elysia395](https://github.com/elysia395/dsh-wallpaper-engine). Current test-branch integration: **[生鱼 / Fish-under-sea](https://github.com/Fish-under-sea)**. Thank you to **[PC2005-cloud / dsh-pet](https://github.com/PC2005-cloud/dsh-pet)** for the public integration APIs, and Bilibili creator **[ZipZipPipe](https://space.bilibili.com/4168597)** for the **AI-girl fan-character designs used as the basis for our new mascots**. These are not official model-vendor characters; attribution does not relicense artwork under MIT. See [all credits](README.md#致谢) and [asset sources](assets/readme/SOURCES.md).

package/README.en.md

@@ -0,0 +1,171 @@
+# DSH Wallpaper Engine
+
+[中文](README.md) · **English** · [Beginner guide](README.beginner.md#english)
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/readme/hero-dark.png">
+  <img src="assets/readme/hero-light.png" alt="DSH Wallpaper Engine: your wallpapers, your glass, your workspace" width="1440">
+</picture>
+
+[![Node.js](https://img.shields.io/badge/Node.js-22.12%2B-8fd6a0?style=flat-square)](https://nodejs.org) [![License](https://img.shields.io/badge/License-MIT-8fd6a0?style=flat-square)](LICENSE) [![Upstream Stars](https://img.shields.io/github/stars/elysia395/dsh-wallpaper-engine?style=flat-square&label=Upstream%20Stars)](https://github.com/elysia395/dsh-wallpaper-engine/stargazers) [![Upstream Forks](https://img.shields.io/github/forks/elysia395/dsh-wallpaper-engine?style=flat-square&label=Upstream%20Forks)](https://github.com/elysia395/dsh-wallpaper-engine/forks) [![Upstream Contributors](https://img.shields.io/github/contributors/elysia395/dsh-wallpaper-engine?style=flat-square&label=Upstream%20Contributors)](https://github.com/elysia395/dsh-wallpaper-engine/graphs/contributors) [![Upstream Release](https://img.shields.io/github/v/release/elysia395/dsh-wallpaper-engine?style=flat-square&label=Upstream%20Release)](https://github.com/elysia395/dsh-wallpaper-engine/releases) [![npm](https://img.shields.io/npm/v/dsh-plugin-wallpaper-engine?style=flat-square)](https://www.npmjs.com/package/dsh-plugin-wallpaper-engine) [![npm Downloads](https://img.shields.io/npm/dm/dsh-plugin-wallpaper-engine?style=flat-square)](https://www.npmjs.com/package/dsh-plugin-wallpaper-engine) [![dsh-pet integration](https://img.shields.io/badge/dsh--pet-Public%20API-8fd6a0?style=flat-square)](https://github.com/PC2005-cloud/dsh-pet/issues/122)
+
+Bring local **Wallpaper Engine Scene, Web and Video wallpapers** into the DSH chat interface, with liquid glass, typography, configuration presets, mascot artwork and optional official dsh-pet integration. The plugin registers no agent tools or prompt text, so it adds no model token overhead.
+
+> **This page describes the unpublished [Fish-under-sea source branch](https://github.com/Fish-under-sea/dsh-wallpaper-engine).** Stars, forks, contributors, releases, npm downloads and Star History refer to the official [elysia395/dsh-wallpaper-engine repository](https://github.com/elysia395/dsh-wallpaper-engine) or its npm package. Cached badges do not mean these branch changes have been merged or published. Identical package version numbers do not guarantee identical source trees.
+
+## Contents
+
+[Features](#features) · [Install](#install) · [Usage](#usage) · [Official dsh-pet integration](#official-dsh-pet-integration) · [Configuration and privacy](#configuration-and-privacy) · [Limitations](#limitations) · [Development](#development) · [Credits](#credits) · [Star History](#star-history)
+
+## Features
+
+| Area | Current capabilities |
+|---|---|
+| Wallpapers | WebWallGL live Scene / Web rendering, video playback, local image / video uploads, wallpaper properties and playlist rotation |
+| Appearance | Liquid glass, accent and surface colors, transparency, blur, borders and independent sidebar controls |
+| Presets | Whole-configuration snapshots, optional font / mascot / avatar assets; the author preset also carries a dark preference and switches the UI theme when applied; JSON import and export |
+| Typography | System fonts, per-role and per-component controls, terminal fonts, font sets and caret color |
+| Mascots | Ten built-in artworks, a 3D ring selector, custom imports and a pull-cord library drawer |
+| Extensions | Optional conversation avatars, click / pointer-trail effects and parallax |
+| Playback | Speed, flip, framing, transitions, cached fps-cap transcodes and occlusion pause |
+| Media | System-output audio spectrum, Now Playing metadata / artwork and opt-in online lyrics |
+| Pet integration | Sidebar pull, mascot grab, native knockback and hiss routines using official dsh-pet APIs |
+
+Scene and Web compatibility depends on the project, WebGL support and browser capabilities. Rendering failures degrade rather than guaranteeing parity with every Wallpaper Engine workshop item. **Application wallpapers are not supported**: this plugin does not launch third-party executables. Custom JPG / PNG / MP4 files stay on your machine.
+
+The current suite has **one main package and seven subpackages, eight packages in total**. A local compressed release-set comparison decreased from approximately **84.88 MiB to 25.12 MiB, about 70.4%**, after removing the bundled pet. This excludes the separately installed official pet and is not a memory-use or Git-repository-size measurement.
+
+## Install
+
+### Current test branch: use the complete source installer
+
+Requirements: **Node.js >=22.12.0, a DSH 0.2 kernel (including 0.2.0-rc.1/rc.2), pnpm and the target host's DSH CLI**. The desktop application's external version number is not its kernel version. Optional pet integration needs a separate official pet installation. Unlike the published build (which asks once with a two-choice dialog and never changes the theme), this branch applies the author preset plus a dark UI automatically on a fresh install and switches the theme whenever a preset that declares a preference is applied; existing save files are never overwritten.
+
+1. Download and extract the complete [review branch `official-pet-bridge-20261020`](https://github.com/Fish-under-sea/dsh-wallpaper-engine/tree/official-pet-bridge-20261020), or clone that branch, not the fork's default branch. Open a terminal in the folder containing `package.json`.
+2. Completely close the target DSH host. Confirm its actual data directory and profile.
+3. Inspect the plan, then run the installer:
+
+```sh
+node scripts/install-source.mjs --profile web --dsh-home "<target DSH data directory>" --dry-run
+node scripts/install-source.mjs --profile web --dsh-home "<target DSH data directory>" --app-closed
+```
+
+For a desktop profile, use `--profile desktop` **with the desktop carrier CLI**. A standalone npm DSH CLI refuses desktop-profile management; changing the profile name does not bypass that protection. If necessary, pass `--dsh-cli "<path to the target CLI lib/bin.js>"`. Do not guess that every host stores its data in `~/.dsh`.
+
+The installer installs source dependencies, builds clients, registers all eight persistent `link:` dependencies and keeps the main bundle as the owner of the plugin rows. Restart the target host afterward. **Keep the source directory in place.** To update, close DSH, update the complete checkout and run the same installer again. Installing only the main package, using a raw `github:` specifier or relying on temporary junctions is not the source deployment procedure.
+
+### npm: only after the complete release set is published
+
+The publisher must build the eight-package set with `npm run pack:release`, publish the seven subpackages first and publish the main package last. The release main manifest declares exact subpackage versions. It does not bundle pet or Electron. A plain root `npm pack` is not a substitute for this complete release set.
+
+**From `1.4.0` on, all eight packages are on npm** — one command installs the whole set (the main package resolves the seven children at exact versions):
+
+```sh
+dsh plugin --profile web add dsh-plugin-wallpaper-engine
+```
+
+To get **unreleased branch changes** you still need the source deployment; the npm name only ever gives you a published version. Desktop installations still require the desktop carrier CLI and a fully closed host. See the [deployment and publishing guide](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/CONTRIBUTING.md).
+
+### Rows and platforms
+
+The main, about, mascot / avatar, media bridge, pet integration, effects, parallax and fonts rows are independently managed. Row changes require reload or restart. Disabling the pet row does not disable wallpapers. Do not additionally enable every subpackage bundle: the main patch owns the row set. Media bridge does not yet have exactly the same whole-block UI-hiding semantics as the other components.
+
+Windows, macOS and Linux use the same source suite. On platforms without the Wallpaper Engine client, use local image / video uploads or point custom-wallpaper storage at existing WE project directories. Imported project directories are read-only and are not deleted through upload management.
+
+## Usage
+
+Open **Settings → Wallpaper Engine**, or pull the mascot cord to open the library drawer. Select wallpapers in the **in-panel library**, not a separate modal. Changes apply immediately and persist on the host.
+
+![Main interface, historical upstream demo](https://github.com/elysia395/dsh-wallpaper-engine/releases/download/media-v1/main-interface.gif)
+
+Historical upstream demonstrations may differ from this branch. The six settings tabs are Library, Appearance, Playback, System, Extensions and About.
+
+- **Library**: selection, rating / type filters, soft hiding and restoration, uploads and rotation lists. Hiding never deletes source files. Rotation needs at least two playable candidates and prepares the next item before switching.
+- **Appearance**: presets, theme, glass, sidebar corners, global UI colors and typography. Theme-following is **off by default**; a manual theme choice takes precedence for the current wallpaper. Presets can carry a light/dark preference — the author preset declares dark and switches the UI theme when applied, a channel independent of theme-following.
+- **Playback**: filters, framing, speed, transitions and audio. Fps-cap transcoding starts with the original and swaps when the cache is ready; unavailable ffmpeg or failed encoding falls back gracefully.
+- **System**: mascot selection, adapter target, occlusion pause and cache locations. The default mascot is DeepSeek; Deepseek_Pro and 菲比啾比 are separate artworks, alongside Claude, DeepSeek, Gemini, GPT, GLM, Grok, Kimi and Qwen. The chibi maid is carried by the author preset rather than the built-in carousel.
+- **Extensions**: optional avatars, click / trail effects and parallax. Disabling an extension removes its own decorations without resetting the wallpaper.
+
+Glass ownership uses per-surface `auto` / `native` fallback. Unknown plugin surfaces are not forcibly cleared. Extra frost selectors have strict limits and must meet positioning and decoration-safety checks. There is no universal guarantee of compatibility with every skin or plugin. See [coexistence](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/docs/COEXISTENCE.md).
+
+System audio capture uses **output loopback, not the microphone**. Online lyrics are off by default and may send track title, artist and album to LRCLIB when enabled. Media runtime support is native per platform: GSMTC / MediaRemote / MPRIS.
+
+## Official dsh-pet integration
+
+Wallpaper now integrates with the separately installed official [dsh-pet](https://github.com/PC2005-cloud/dsh-pet) through public APIs. Thank you to [PC2005-cloud](https://github.com/PC2005-cloud) for the interfaces and [cross-plugin discussion #122](https://github.com/PC2005-cloud/dsh-pet/issues/122). This is API integration, **not a bundled fork, a third-party file patch or a joint upstream release claim**.
+
+1. Install and enable an official pet build exposing same-page `petApi7340.pose/progress` and HTTP config, lock, anim, position and throw APIs. The `0.3.7` version number alone is insufficient to identify these capabilities.
+2. Set the pet to display on the web surface, and set the Wallpaper mascot to official-sidebar mode.
+3. Open **Ctrl+Shift+D**, refresh targets, select the intended petId and try the sidebar, mascot-grab, knockback and hiss routines.
+
+| Boundary | Behavior |
+|---|---|
+| Missing pet / hidden target | Integration stops; wallpaper and the original sidebar action still work. No silent switch to another pet |
+| Multiple displays | The same pet's actions follow official shared state across pages / desktop; no instance isolation is promised |
+| Bubbles | Drawn by the bridge only in the initiating page; can outlive action ownership; official bubbles are neither occupied nor cleared |
+| Tuning | Target selection, four routine pages, timing, stop, reset and JSON export; runtime parameter overrides should be exported before refresh |
+| Motion | Uses official position / throw; no pet DOM takeover, private React fields or per-frame HTTP |
+| Verification | Protocol, HTTP, playback scheduling and bridge UI checks passed; complete official React-pet and desktop visual acceptance remains outstanding |
+
+Native position interpolation uses wall-clock time and is not guaranteed to track buffered video frame by frame. Existing bundled-pet dependencies, bundle selections, data and earlier external patches are **not automatically removed**. Close the host, disable the old bundled row and follow the [migration and integration guide](packages/pet-link/README.md). The official pet's files, configuration and animation pools are not rewritten.
+
+## Configuration and privacy
+
+Wallpaper settings live in `~/.dsh-wallpaper-engine/config.json`, independent of the browser port. Caches and uploads default to subdirectories under the same data root and can be moved from the UI. Migration moves recognized plugin files, not unrelated files in the target directory. Pet target selection and exported runtime tuning have their separate bridge lifecycle; they are not all part of the host configuration file.
+
+| Variable | Purpose |
+|---|---|
+| `DSH_WE_DATA_DIR` | Override the whole plugin data root |
+| `DSH_WE_CACHE_DIR` / `DSH_WE_UPLOAD_DIR` | Override cache / upload roots |
+| `DSH_WE_STEAM_ROOT` / `DSH_WE_ASSETS_DIR` | Override Steam discovery / official WE resources |
+| `DSH_WE_FFMPEG` / `DSH_WE_FFMPEG_URL` | Explicit ffmpeg executable / download source |
+| `DSH_WE_TRANSCODE_TIMEOUT_MS` | Transcode time budget |
+| `DSH_WE_MEDIA_BRIDGE` / `DSH_WE_MEDIA_BRIDGE_URL` | Explicit media bridge / source |
+| `DSH_WE_MEDIA_BRIDGE_TAG` / `DSH_WE_MEDIA_BRIDGE_SHA256` | Version and required integrity information for custom versions |
+| `DSH_WE_MEDIA_LEGACY` / `DSH_WE_MEDIA_NO_AUDIO` | Built-in fallback / metadata-only mode |
+| `DSH_WE_MEDIA_PROVIDER` | `mock` for development |
+| `DSH_WE_MEDIA_IDLE_MS` / `DSH_WE_MEDIA_DEBUG` | Idle shutdown / diagnostic output |
+
+Wallpaper files stay local. Runtime downloads, GitHub repository statistics and opt-in lyrics access external services; this is not a claim of fully offline operation.
+
+## Limitations
+
+- Application wallpapers are unsupported. Scene compatibility depends on assets, scripts, WebGL and drivers.
+- Three-platform installation does not imply an official Wallpaper Engine client exists on all three platforms.
+- Desktop minimize / restore can still expose a brief shell-side white frame; the plugin cannot fully control the host window base plate.
+- Video and scene occlusion pause differ from externally hosted iframe behavior. Focus-loss pause is exposed only for the appropriate browser adapter.
+- Optional `dsh-better-sidebar` integration has its own surface controls; browsers without backdrop filtering use solid fallback.
+- Pet action synchronization and bridge-only bubbles are intentional interface boundaries, not old private-controller parity.
+- A preset's light/dark preference travels in the preset body only: export / import round-trips do not carry that section, so a shared preset never changes the recipient's theme.
+
+## Development
+
+See the current [contribution guide](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/CONTRIBUTING.md), [changelog](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/docs/CHANGELOG.md), [upgrade notes](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/docs/UPGRADING.md), [rendering design](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/docs/HOW-IT-WORKS.md) and [troubleshooting](https://github.com/Fish-under-sea/dsh-wallpaper-engine/blob/official-pet-bridge-20261020/docs/TROUBLESHOOTING.md). Generated clients are built from source; do not edit generated bundles by hand. The npm package does not ship `docs/`, so these technical links use repository URLs.
+
+Report branch-specific installation or pet-integration problems to the [current fork](https://github.com/Fish-under-sea/dsh-wallpaper-engine/issues), with versions, platform, reproduction steps and sanitized logs. Shared upstream problems belong in the [official tracker](https://github.com/elysia395/dsh-wallpaper-engine/issues). Never include credentials. Community QR codes are available in the [Chinese README](README.md#联系方式).
+
+## Credits
+
+Contributions are grouped by work, not ranked. See the official [Contributors](https://github.com/elysia395/dsh-wallpaper-engine/graphs/contributors) and [merged PRs](https://github.com/elysia395/dsh-wallpaper-engine/pulls?q=is%3Apr+is%3Amerged) for the maintained history.
+
+- **[elysia395](https://github.com/elysia395)**: project creation, upstream maintenance, releases, presets and community.
+- **[生鱼 / Fish-under-sea](https://github.com/Fish-under-sea)**: current source-branch integration, whole-configuration presets and asset import / export, mascot carousel, source deployment and release closure, official pet bridge, bubble / routine / tuning work and regression documentation. Earlier work: [#173](https://github.com/elysia395/dsh-wallpaper-engine/pull/173), [#180](https://github.com/elysia395/dsh-wallpaper-engine/pull/180), [integration PR #251](https://github.com/elysia395/dsh-wallpaper-engine/pull/251). Some latest source work remains unpublished.
+- **[YV3507](https://github.com/YV3507)**: rendering and frame-pipeline fixes, liquid-glass tokens, architecture, documentation, regression guards and community integration.
+- **[oneincase](https://github.com/oneincase)**: [WebWallGL](https://github.com/oneincase/webwallgl), [media-bridge](https://github.com/oneincase/media-bridge), live rendering, cross-platform media and performance work.
+- **[yuxilao](https://github.com/yuxilao)** and **[Jerry / ruijiaang-lab](https://github.com/ruijiaang-lab)**: Linux scene-rendering exploration, performance / rotation work, and early macOS / WaifuX compatibility and contribution paths.
+- **Community contributors**: WTStarMark, levodoubt, Willhamster, 383891598, SiriLee, libiwolve, 0-007pro, jujubaoj646-star, xiahou001, wilianyichen, hecoococ, ShamSky88, Rekk0, Y1X1n, wwexplorer, jassdingk, w-sli and everyone helping through issues, documentation and device testing. See the [full contribution summary](README.md#致谢).
+- **[PC2005-cloud / dsh-pet](https://github.com/PC2005-cloud/dsh-pet)**: official pet APIs and cross-project integration support.
+- **Bilibili creator [ZipZipPipe](https://space.bilibili.com/4168597)**: thank you for the **AI-girl fan-character designs used as the basis for our new mascots**. These are fan creations, not official model-vendor characters or endorsements. Attribution does not relicense the artwork under MIT.
+
+The README's retro window layout references [MaiBot](https://github.com/Mai-with-u/MaiBot); Jersey 20 uses SIL OFL 1.1. Source artwork and character rights remain with their respective owners. See [asset sources](assets/readme/SOURCES.md). The code's MIT license does not replace character, image or font permissions. Wallpaper Engine and workshop content belong to their respective owners; this is not an official Wallpaper Engine product.
+
+## Star History
+
+Official upstream history, not fork statistics:
+
+<a href="https://star-history.com/#elysia395/dsh-wallpaper-engine&Date">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=elysia395/dsh-wallpaper-engine&amp;type=Date&amp;theme=dark">
+    <img src="https://api.star-history.com/svg?repos=elysia395/dsh-wallpaper-engine&amp;type=Date" alt="Official upstream Star History" width="960">
+  </picture>
+</a>

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# dsh-folia
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH Desktop 的壁纸插件。基于 [dsh-plugin-wallpaper-engine](https://www.npmjs.com/package/dsh-plugin-wallpaper-engine)（MIT，© 2026 elysia395）二次开发，**保留其全部功能**，并增加一个自建站点数据源。
+
+## 与上游的差异
+
+**全仓库只有一处功能改动**，位于 `lib/routes/inventory.js`：
+
+```js
+const payload = await buildInventory();
+const remote = await foliaRemote();          // 拉站点 manifest
+const merged = remote.length
+  ? { ...payload, wallpapers: [...(payload.wallpapers || []), ...remote] }
+  : payload;
+```
+
+`foliaRemote()` 负责把站点上的视频壁纸转成插件认识的条目形状，并带 60 秒缓存。站点不可达时返回空数组，**不影响本地 Wallpaper Engine 库**。
+
+其余 143 个文件与上游 1.4.0 完全一致。
+
+## 站点数据源
+
+默认地址：`https://folia-major-3t6.pages.dev`
+
+可通过环境变量覆盖：
+
+```bash
+DSH_FOLIA_SITE=https://your-site.pages.dev
+```
+
+站点需要提供 `/manifest.json`：
+
+```json
+{
+  "images": [
+    {
+      "id": "azure-loop",
+      "file": "azure-loop.mp4",
+      "title": "Azure Loop",
+      "kind": "video",
+      "url": "/wallpapers/azure-loop.mp4",
+      "preview": "/previews/azure-loop.jpg"
+    }
+  ]
+}
+```
+
+只注入 `kind: "video"`（或 `.mp4` / `.webm` 后缀）的条目——上游没有静态图片的渲染管线。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-folia-wallpaper
+```
+
+或从本仓库安装：
+
+```bash
+dsh plugin --profile web add github:lehua-art/dsh-folia
+```
+
+安装后重启 DSH Desktop。
+
+## 功能（全部来自上游）
+
+- 场景壁纸实时渲染（WebWallGL，WebGL）
+- 视频壁纸播放
+- 玻璃材质、可读性地板、透明度/模糊调节
+- 壁纸库面板：列表/卡片、标签、排序、属性
+- 播放列表、轮播、遮挡暂停、自动画质
+- 字体系统、视差层、特效层、吉祥物头像、媒体桥
+
+## 目录
+
+| 路径 | 说明 |
+| :-- | :-- |
+| `lib/` | 宿主半边 + 浏览器半边（上游 31k 行客户端） |
+| `lib/webwallgl/` | 场景渲染页（引擎为 npm 依赖 `webwallgl`） |
+| `lib/routes/inventory.js` | **唯一改动的文件** |
+| `cordis.patch.yml` | 插件行注册（8 个宿主行） |
+
+## 许可
+
+MIT。上游署名与许可见 `LICENSE`。

package/assets/readme/OFL-Jersey20.txt

@@ -0,0 +1,93 @@
+Copyright 2023 The Soft Type Project Authors (https://github.com/scfried/soft-type-jersey)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/readme/SOURCES.md

@@ -0,0 +1,17 @@
+# README 视觉素材来源
+
+本轮 README 首屏与分节横条按维护者提供的 [MaiBot README](https://github.com/Mai-with-u/MaiBot) 截图复刻视觉结构：立体窗口边框、像素标题、通风栅格、状态灯、四格信息卡与键帽入口。对应项目的公开 SVG 用于核对布局和色值，未复制它的 SVG 路径、人物图、鱼形装饰、遥测数据或趋势排名徽章。
+
+- 排版源稿：[hero.html](hero.html)。深浅主题 PNG 是真实 HTML / CSS 的静态截图，不是产品运行截图或生成式插图。
+- 右侧角色：复用项目原始 [icon.png](../../icon.png)，未重画或重编码原图。
+- 挂件：复用 [菲比啾比](../rope/phoebe.png)，未修改运行时 PNG。角色权利保持原有归属，本页不重新授权。
+- 字体：Jersey 20，Copyright 2023 The Soft Type Project Authors。字体来自 [Google Fonts](https://github.com/google/fonts/tree/main/ofl/jersey20)，按 [SIL Open Font License 1.1](OFL-Jersey20.txt) 使用。原字体文件保留供复现，不作为插件运行依赖。
+- 信息卡：源码版本来自项目包声明；三类 WE 壁纸为 Scene / Web / Video；十只立绘来自内置角色；七个子包来自项目子包清单。这些是当前源码信息，不是实时在线人数、下载遥测或门禁结果。
+- 资源尺寸、摘要、实际截图元素与生成时间记录在 [metadata.json](metadata.json)，仅登记本轮实际使用的 56 份双主题展示图。旧创作桌面配饰不再用于横幅，未纳入本轮展示素材与发布包。
+
+## 新吉祥物与联动致谢
+
+- **AI 娘二创形象**：感谢 B 站 UP 主 [ZipZipPipe](https://space.bilibili.com/4168597) 的角色创作，为本项目的新吉祥物提供形象基础。此项是形象创作署名，不把 AI 娘认定为模型厂商官方角色或背书，也不据此改授 MIT。项目图标、原有菲比素材与其他角色仍按各自来源归属，不将它们全部归于同一作者。
+- **官方 pet 联动**：感谢 [PC2005-cloud / dsh-pet](https://github.com/PC2005-cloud/dsh-pet) 提供公开接口并参与 [接口讨论 #122](https://github.com/PC2005-cloud/dsh-pet/issues/122)。当前桥接不分发官方 pet 运行时，不修改其文件；本项为跨项目接口致谢，不代表角色素材授权或联合发布。
+
+本页没有使用 MaiBot 的项目名称、人物、用户数字或排名作为本项目背书。项目主许可证不自动替代字体及角色各自的权利。