dsh-mpkg-wallpaper 3.3.2 → 3.4.0

package/README.en.md

@@ -35,6 +35,15 @@ A plugin for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harn
 - **Unified fog** (full-screen mask with one fog color, strength slider), **panel wallpaper-matching color** (auto sample + strength slider + custom picker), **adaptive text + blue cleanup** (brand unified, custom picker), **dark-background text readability**, **todo-list frost**
 - Appearance tab also has: floating cards, clock, etc.
 
+**🧩 dsh-better-sidebar adaptation (shown when that plugin is detected)**
+- When [dsh-better-sidebar](https://github.com/) is installed, an **adaptation section** appears in the "Appearance / Other" tabs with a master toggle + sub-toggles:
+  - **Floating double-layer fix** (bsFloat): makes the floating sidebar's inner `pane/tabBar` background transparent so no double solid rectangle appears when floating
+  - **Reveal level** (bsReveal + bsRevealAlpha slider): how much wallpaper shows through the better-sidebar surface (higher = more transparent)
+  - **Follow theme / Aqua** (bsAlpha / bsAqua): better-sidebar panel follows the theme base / the unified-fog color
+  - **Bottom panel avoidance** (bsBottomAvoid): the bottom panel stays aligned with the DSH center column (handled by better-sidebar's own ResizeObserver — no manual offset)
+  - Font follow (bsFont) and other sub-toggles
+- The host `/ping` endpoint auto-detects whether better-sidebar is installed; the section is hidden when it is not
+
 **🎬 Lens & picture**
 - Lens zoom (10–2000%) & pan, brightness (50–150%), light sharpen, Deep diving background box
 
@@ -46,19 +55,29 @@ A plugin for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harn
 
 **🖼️ Local wallpaper library**
 - **Steam auto-discovery** + **custom folder** (any directory + cross-platform folder picker; .mpkg files and workshop folders can be mixed freely)
-- **Switching & rotation**: prev/next one-click, timed auto-rotation (interval adjustable)
+- **Switching & rotation**: prev/next one-click, timed auto-rotation (interval adjustable); rotation-list checkboxes keep scroll position (no jump-to-top), and unnamed lists get auto-numbered (`Unnamed list N`) so they never collide
 
 **🛡️ Safety & coexistence**
 - **Conflict detection**: auto-disables when another wallpaper/theme plugin is detected
 - **Security boundaries**: .exe/application wallpapers are completely excluded (virus-injection defense); custom folders only read media files; host routes validate against path traversal; web-wallpaper iframes are sandboxed
 
 **🔄 Updates**
-- "Check update" compares **versions** (semver) — un-pushed local changes don't false-positive; "Apply update" pulls the latest code from GitHub, restart to take effect
+- "Check update" compares **versions** (semver) — un-pushed local changes don't false-positive; **the plugin marketplace is the recommended path** (its semver check matches); "Apply update" pulls the latest code from GitHub, restart to take effect
 
 **💾 Backup & restore / settings persistence**
 - The "Other" tab provides **backup & restore**: export appearance settings (Appearance / Unified blur / UI blur / Aqua / Other) to a **shareable JSON file**, import to restore — not the current wallpaper or scanned dirs
 - **Settings persist to a host file**: besides localStorage, settings are written to `~/.dsh-mpkg-wallpaper/settings.json` — **survives port changes / browser-data clears** (following elysia395 v0.4.0)
 
+## ⚡ Performance & stability
+
+- **mpkg head-only reads** (no whole-file load): container parsing reads only the first 2MB head (`openSync+readSync`), so even an 834MB mpkg cold-starts near-instantly — fixes the old "read whole file then slice" 9-second load
+- **Restart self-healing**: custom-folder wallpapers are rebuilt by **filename token** after restart (media 404 retries exhausted → re-parse by mpkgKey); the wallpaper no longer comes back blank after restart
+- **Re-entry guards**: both `applyFromStorage` and the Aqua theme watcher carry a re-entry flag + debounce, preventing "overrideTokens → theme/change → re-entry" infinite loops (the dark-mode + unified-fog scenario once froze the main thread)
+- **Scene cache is byte-bounded**: layer cache has a 128MB byte budget + count cap double-guard; scene.pkg is only read in full on a cache miss (stat-first)
+- **Listeners/timers register once**: storage listener, 60s slot check, inline-style watcher, etc. are de-duplicated — repeated apply/RTC reconnects never accumulate
+- **Lazy loading prevents OOM**: time-variation wallpapers extract only the current slot; hybrid streams large files with minimal memory
+- **Weak-device throttling**: heavy compositing (full-screen backdrop-filter over streaming video) is globally throttled; for extreme WebView combos, Edge / desktop browsers still give the best experience
+
 ## Supported Types & Status
 
 | Type | Web behavior | Notes |
@@ -101,7 +120,7 @@ The plugin offers these partial solutions (chosen automatically by scene content
 
 ## Web Wallpapers (Experimental)
 
-- HTML wallpapers load full-screen in a **sandboxed iframe** (`allow-scripts` isolation; **mute toggle, default on**; does not auto-reload after refresh — refresh the page to recover if frozen)
+- HTML wallpapers load full-screen in a **sandboxed iframe** (`allow-scripts` isolation; **mute toggle, default on**; **webUrl is persisted** — auto-recovers after refresh / route changes / RTC reconnects without losing config; refresh the page manually if it ever freezes)
 - **Risk preflight**: auto-classified during scan; badges shown in the list and confirm dialog:
   - **⚠heavy animation**: Spine/L2D skeletal wallpapers — may freeze on low-end devices
   - **🌐external**: depends on external SDK/CDN (e.g. miHoYo event pages) — may fail to load
@@ -111,12 +130,11 @@ The plugin offers these partial solutions (chosen automatically by scene content
 
 - **Source**: master switch, hybrid, mpkg file, image/video files, custom folder (can point at the workshop root), local library (Steam scan), switching/rotation, **time-variation slot lock**
 - **Wallpaper**: mute, mirror flip (horizontal/vertical), video playback speed, adjustable options (mpkg read-only / web wallpapers editable), decode fps cap, resolution cap, ffmpeg status
-- **Appearance**: theme color, floating, frosted blur, lens zoom/position, brightness
+- **Appearance**: theme color, floating, frosted blur, lens zoom/position, brightness, **wallpaper reveal** (sidebar/title-bar visibility, title-bar frost amount, sharpen)
 - **Unified blur**: full-screen blur + sidebar/title-bar fog, chat follow, new-chat follow
 - **UI blur**: dialog/settings/popup/popover/mask/sidebar frost each independent
-- **Wallpaper reveal**: sidebar/title-bar visibility, title-bar frost amount, sharpen
 - **Aqua**: unified fog / panel tint / adaptive text experiment toggles
-- **Other**: clock, update check/apply, **backup & restore**, restore all defaults
+- **Other**: clock, update check/apply, **backup & restore**, restore all defaults; the better-sidebar **adaptation section** appears here when that plugin is installed
 
 ## Installation
 

package/README.md

@@ -35,6 +35,15 @@
 - **统一雾**（全屏遮罩统一雾色，强度独立滑条）、**面板匹配壁纸色**（自动取色 + 强度滑条 + 自定义取色盘）、**自适应文字色 + 蓝色清理**（品牌色统一，带自定义取色盘）、**深底文字可读增强**、**任务列表磨砂**
 - 外观 tab 里还有：悬浮卡片、时钟等
 
+**🧩 dsh-better-sidebar 适配（检测到该插件后显示）**
+- 已安装 [dsh-better-sidebar](https://github.com/) 时，「外观 / 其他」tab 自动出现**适配分类**：总开关 + 子开关：
+  - **悬浮双层修复**（bsFloat）：让悬浮侧边栏的 `_panel` 内层 `pane/tabBar` 背景透明，避免悬浮时出现双重实色矩形
+  - **透出程度**（bsReveal + bsRevealAlpha 滑条）：better-sidebar 表面透出壁纸的浓度可调（越高越透）
+  - **跟随主题 / Aqua**（bsAlpha / bsAqua）：better-sidebar 面板跟随主题底色 / 跟随统一雾取色
+  - **底部面板避让**（bsBottomAvoid）：底部面板实时对齐 DSH 中心列（better-sidebar 自身 ResizeObserver 负责，无需手动偏移）
+  - 字体跟随（bsFont）等其余子开关
+- 主机端 `/ping` 自动探测 better-sidebar 是否安装；未安装时该分类隐藏
+
 **🎬 镜头与画面**
 - 镜头缩放（10–2000%）与平移、画面亮度（50–150%）、轻度锐化、Deep diving 背景框
 
@@ -46,19 +55,29 @@
 
 **🖼️ 本地壁纸库**
 - **Steam 自动发现** + **自定义目录**（任意文件夹 + 跨平台目录选择器；mpkg 文件与 workshop 文件夹混合放置都能识别）
-- **壁纸切换与轮换**：上一个/下一个一键切换、定时自动轮换（间隔可调）
+- **壁纸切换与轮换**：上一个/下一个一键切换、定时自动轮换（间隔可调）；轮换列表勾选后滚动保持不跳顶，未命名列表自动加序号（`未命名列表 N`）不重名
 
 **🛡️ 安全与共存**
 - **冲突检测**：检测到其他壁纸/主题插件自动关闭本功能
 - **安全边界**：.exe/application 壁纸完全排除（防病毒注入）；自定义目录只读媒体文件；宿主路由有路径穿越校验；网页壁纸 iframe 沙箱隔离
 
 **🔄 更新**
-- 「检查更新」按**版本号**对比（semver），本地未推送改动不误报；「一键更新」从 GitHub 拉最新代码写回，重启生效
+- 「检查更新」按**版本号**对比（semver），本地未推送改动不误报；**推荐先到插件市场更新**（semver 检测与市场一致）；「一键更新」从 GitHub 拉最新代码写回，重启生效
 
 **💾 备份与恢复 / 设置持久化**
 - 「其他」tab 提供**备份与恢复**：导出外观类设置（外观 / 统一虚化 / 界面虚化 / Aqua / 其他）为**可分享的 JSON 文件**，导入即还原——不含当前壁纸与扫描目录
 - **设置持久化到宿主端文件**：设置除浏览器 localStorage 外加存 `~/.dsh-mpkg-wallpaper/settings.json`，**换端口 / 清浏览器数据不丢失**（参考 elysia395 v0.4.0 的做法）
 
+## ⚡ 性能与稳定性
+
+- **mpkg 只读头部**（不再整文件载入）：容器解析只读前 2MB 头（openSync+readSync），834MB 大 mpkg 冷启动也接近秒开——修掉了早期「读整个文件再切片」造成的 9 秒加载
+- **重启自愈**：自定义目录壁纸重启后按**文件名 token** 自动匹配重建（media 404 重试耗尽后按 mpkgKey 重新解析），重启后壁纸不再空白
+- **防重入锁**：`applyFromStorage` 与 Aqua 主题监听均带防重入标志 + 去抖，杜绝「overrideTokens → theme/change → 重入」死循环（深色 + 统一雾场景曾实测卡死主线程）
+- **场景缓存按体积限流**：图层缓存 128MB 字节预算 + 条数上限双兜底；场景 pkg 只在缓存未命中时读整文件（stat 优先）
+- **监听/定时器只注册一次**：storage 监听、60s 时段检查、内联样式 watcher 等均去重，反复 apply/RTC 重连不累积
+- **懒加载防 OOM**：时间变化壁纸只提取当前时段；hybrid 大文件流式播放内存占用极低
+- **弱设备降级**：对高负载合成（全屏 backdrop-filter + 流媒体视频叠加）做了整体节流优化；不同 WebView 的极端组合问题仍建议用 Edge / 桌面浏览器获得最佳体验
+
 ## 支持类型与现状
 
 | 类型 | Web 端表现 | 说明 |
@@ -101,7 +120,7 @@
 
 ## 网页壁纸（Web，实验性）
 
-- HTML 壁纸在**沙箱 iframe** 中全屏加载（`allow-scripts` 隔离；有静音开关，默认开；刷新后不自动重载——卡住时刷新页面即可恢复）
+- HTML 壁纸在**沙箱 iframe** 中全屏加载（`allow-scripts` 隔离；有静音开关，默认开）；**webUrl 持久化**——刷新 / 路由切换 / RTC 重连后自动恢复，不会丢配置（卡住时手动刷新页面即可恢复）
 - **风险预检**：扫描时自动分类，列表与确认框标注：
   - **⚠重动画**：Spine/L2D 骨骼动画壁纸，低性能设备可能卡住界面
   - **🌐外网**：依赖外网 SDK/CDN（如米哈游事件页），加载可能失败
@@ -109,14 +128,13 @@
 
 ## 设置分组（顶部 Tab）
 
-- **来源**：总开关、hybrid、mpkg 文件、图片/视频文件、自定义目录（可指 workshop 主目录）、本地壁纸库（Steam 扫描）、壁纸切换/轮换、**时间变化壁纸的时段锁定**
+- **背景来源**：总开关、hybrid、mpkg 文件、图片/视频文件、自定义目录（可指 workshop 主目录）、本地壁纸库（Steam 扫描）、壁纸切换/轮换、**时间变化壁纸的时段锁定**
 - **壁纸设置**：静音、镜像翻转（水平/垂直）、视频倍速、可调参数（mpkg 只读 / 网页壁纸可改）、解码帧率上限、分辨率上限、ffmpeg 状态
-- **外观**：主题颜色、悬浮、磨砂模糊、镜头缩放/位置、亮度
+- **外观**：主题颜色、悬浮、磨砂模糊、镜头缩放/位置、亮度、**透出壁纸**（侧边栏/标题栏透出、标题栏磨砂程度、锐化）
 - **统一虚化**：整屏虚化 + 侧边栏/标题栏白雾、聊天区跟随、新会话跟随
 - **界面虚化**：对话框/设置面板/弹窗/弹层/遮罩/侧边栏磨砂各自独立
-- **透出壁纸**：侧边栏/标题栏透出、标题栏磨砂程度、锐化
 - **Aqua**：统一雾/面板取色/自适应文字等实验开关
-- **其他**：时钟、更新检查/热更新、**备份与恢复**、恢复所有默认设置
+- **其他**：时钟、更新检查/热更新、**备份与恢复**、恢复所有默认设置；安装 better-sidebar 时此处出现**适配分类**
 
 ## 安装