dsh-background-by-model 0.9.1 → 0.9.2

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-> The full release history lives here; the **Recent optimizations** section of [README.md](./README.md#recent-optimizations) lists only the two most recent releases (v0.9.1 / v0.9.0).
+> The full release history lives here; the **Recent optimizations** section of [README.md](./README.md#recent-optimizations) lists only the two most recent releases (v0.9.2 / v0.9.1).
+
+## v0.9.2
+
+- **The Config tab reports how many unreferenced images there are, and clears them** — images are stored at full fidelity, so an interrupted upload, a failed file deletion or a wholesale replacement can leave a `modelbg-<slot>` file that no rule references. That residue is invisible by construction: boot reads the slots the config names, so an orphaned file is never loaded, never painted and never reported anywhere.
+- **Read first, delete second** — the card prints how much is cleanable and how many files that is, and only then offers the button; the figures describe what the press would free, not the store's total (a total file count reads as "delete all eight"). The sweep re-reads afterwards rather than subtracting, so a file that failed to delete still counts, and the toast names any that resisted.
+- **The sweep asks nothing** — one press deletes. What goes is by definition referenced by no rule, and a "confirm?" here only teaches people to click through; the safety moved into the **gate** (an unreadable config disables the button). The numbers are still read first — announcing a size after deleting is the cleanup nobody would agree to.
+- **A `modelbg-h-*` file is prunable** — that slot belongs to no config (the festival art lives in `holiday-cache/`, and the slot is read-only), so this is the only path that can ever remove one. `referencedSlots` deliberately takes RULES only, and `check:store` pins the call site so a future edit cannot add the holiday entries back.
+- **An older host reads as "unknown", not "0 B"** — the node half answers two new methods (`storeUsage`, `pruneOrphans`), and a bundle talking to a node half from before them shows "restart DSH" instead of claiming a measurement nobody made.
+- **`check:store`** — the two decisions (`referencedSlots` / `orphanSlots`) on plain node: a picture in use is never an orphan, `keep` only ever spares a slot (the gap between an upload's bytes and the rule entry that names them), and the client sends rule slots only. `check:node` covers the sweep through the real RPC handler.
+- **The READMEs catch up with the checks** — they had been claiming ten since v0.8.1's `check:watchdogs` and `check:scheme` landed; both are now listed, as is `check:store`.
 
 ## v0.9.1
 

package/CHANGELOG.zh.md

@@ -1,6 +1,16 @@
 # 更新日志
 
-> 这里保留完整的历史记录；[README.zh.md](./README.zh.md#近期优化) 的「近期优化」一节只列最近两个版本（v0.9.1 / v0.9.0）。
+> 这里保留完整的历史记录；[README.zh.md](./README.zh.md#近期优化) 的「近期优化」一节只列最近两个版本（v0.9.2 / v0.9.1）。
+
+## v0.9.2
+
+- **「配置」页会报出有多少没人引用的图片，并把它们清掉** —— 图片按原图保存，所以一次被中断的上传、一次失败的文件删除或一次整批替换，都可能在磁盘上留下一个没有任何规则引用的 `modelbg-<slot>` 文件。这种残留天生不可见：启动只读配置里点名的槽位，所以孤儿文件从来不会被加载、被画出、也不会出现在任何地方。
+- **先读、后删** —— 卡片先显示「可清理多少 MB / 几个文件」，然后才给出按钮；数字只描述这一按会释放什么（不是「正在使用多少」或总共几个文件 —— 后者会被读成「八个都要删」）。清理完重新读一次而不是用减法，所以没删掉的文件仍然算在里面，提示里也会点名是哪几个。
+- **清理不问确认** —— 点一下就删。要删的文件按定义不被任何规则引用，而「确认」在这里只教人不看就点；安全性改放在**前置判断**上：配置读不出来时按钮是灰的。数字仍然是先读的 —— 先删后报数才是没人会同意的那个操作。
+- **`modelbg-h-*` 可以被清掉** —— 那个槽位不属于任何配置（节日画在 `holiday-cache/`，槽位只读），所以这是唯一能删掉它的路径。`referencedSlots` 刻意只接**规则**，`check:store` 钉住调用点，免得以后的改动把节日条目加回去。
+- **旧版宿主编译出来是「读不到」，不是「0 B」** —— node 半边新增两个方法（`storeUsage`、`pruneOrphans`），而对着旧 node 半边的浏览器半边会显示「重启 DSH」，而不是报一个没人量过的数字。
+- **`check:store`** —— 两个判定（`referencedSlots` / `orphanSlots`）在纯 node 上跑：正在用的图永远不会是孤儿、`keep` 只可能**放过**槽位（上传的字节落地与命名它的规则条目之间的那段空隙）、以及客户端只送规则槽位。`check:node` 通过真实 RPC 处理器覆盖清理本身。
+- **两份 README 追上校验的条数** —— 从 v0.8.1 的 `check:watchdogs` 与 `check:scheme` 起它们就一直写着「十道」；现在都列出来了，`check:store` 也在内。
 
 ## v0.9.1
 

package/README.md

@@ -130,9 +130,20 @@ One click on the Config tab downloads the author's own configuration — rules,
 
 - **Hosted in the store's own shape** (`preset/preset.json`, `preset/theme-config.json`, one `modelbg-<slot>` file per wallpaper), so it stays editable on GitHub and publishing it is a `cp`.
 - **Every interface number in it is what the plugin already ships with**, so on a new install the button adds rules and pictures; on a store you have already tuned it resets those too, because it is a whole configuration and not a patch.
-- **The download comes before the question**, so the confirmation can say what is actually in hand — and the wipe comes after the download, never before it. It is the only destructive action in the panel.
+- **The download comes before the question**, so the confirmation can say what is actually in hand — and the wipe comes after the download, never before it. It is the only card in the panel that **asks before it deletes**.
 - **One missing wallpaper fails the whole attempt and names the slot**, and every file retries on its own, keeping what arrived for the next press.
 
+### Image storage cleanup
+
+The last card on the Config tab. Images are stored at **full fidelity**, so an interrupted upload, a failed file deletion or a wholesale config replacement can leave a file on disk that no rule references any more — and on a tidy machine that number is normally **0**. The card reads the numbers, and the button deletes **without asking**.
+
+- **Read first, delete second** — it shows how much is cleanable and how many files that is, before it offers the button. A cleanup whose size is announced afterwards is a cleanup nobody agrees to. The numbers describe only **what the press would free**: "2.1 MB in use" answers a question nobody asked on this card, and a total file count reads as "eight to delete" when the honest answer is one.
+- **Only unreferenced files** — every byte a current rule uses is untouched, and the config itself is never written. The card re-reads after the sweep instead of subtracting, so a file that failed to delete still counts.
+- **Failures are named** — one undeletable file does not protect the other six, and it is not reported as success either: the toast lists which ones.
+- **No confirmation step** — what it deletes is by definition referenced by no rule, and is not a choice made from a working set, so a "confirm?" here only teaches people to click through. The safety is in the **gate**: when the config cannot be read the button is disabled (next bullet), rather than seven files being listed and then asked about.
+- **It also clears a stray `modelbg-h-*`** — that slot belongs to no config (festival art lives in `holiday-cache/`, and the slot is read-only), so this is the only path that can ever remove such a file.
+- **An older host reads as "unknown", not "0 B"** — the two nothings must not look the same.
+
 ## Settings
 
 Settings → **Theme** now has three tabs:
@@ -141,7 +152,7 @@ Settings → **Theme** now has three tabs:
 | --- | --- | --- |
 | **Interface** | Global, shared by every model | Opacity for the main background, left panel, right panel, cards & panels, input & controls, settings panel, conversation text box, trajectory page and every plugin page |
 | **Model Background** | Per rule, per image | The ordered rule list, the live match readout, and each rule's images (filmstrip), **per-image layout mode, framing and theme color**, plus the rule's opacity, brightness, blur and [rotation](#image-rotation) |
-| **Config** | — | The global [switch effect](#switch-effect-global), the whole rule set as a file — [recommended profile](#recommended-profile), import and export (`dsh-background-by-model-theme.json`) — plus the single [holiday background](#holiday-backgrounds) switch |
+| **Config** | — | The global [switch effect](#switch-effect-global), the whole rule set as a file — [recommended profile](#recommended-profile), import and export (`dsh-background-by-model-theme.json`) — plus the single [holiday background](#holiday-backgrounds) switch and the [image storage cleanup](#image-storage-cleanup) |
 
 The old **Color** tab is gone — the theme color is now a property of each rule — and the old **Background** tab became **Model Background**.
 
@@ -184,7 +195,7 @@ npx @deepseek-ai/dsh web
 git clone https://github.com/HarmlessFunny/dsh-background-by-model.git
 cd dsh-background-by-model
 pnpm install
-pnpm test            # builds lib/, typechecks, runs the ten checks
+pnpm test            # builds lib/, typechecks, runs the thirteen checks
 ```
 
 `pnpm run bundle` rebuilds `lib/` on its own. Either has to run before the plugin can load: a fresh clone has no `lib/`.
@@ -206,7 +217,7 @@ To mount a working copy into a profile instead, add it to the profile's `package
 
 After changing anything under `src/`, run `pnpm run bundle` again — the mounted profile loads `lib/`, so edits do not take effect until the bundle is rebuilt.
 
-`pnpm test` builds, typechecks and runs ten checks, none of which needs a dependency, a transformer or a browser. Each can also be run on its own with `pnpm check:holiday` / `pnpm check:rotation` / `pnpm check:transition` / `pnpm check:repaint` / `pnpm check:code-plate` / `pnpm check:image-mode` / `pnpm check:rules` / `pnpm check:preset` / `pnpm check:ui` / `pnpm check:node`:
+`pnpm test` builds, typechecks and runs thirteen checks, none of which needs a dependency, a transformer or a browser. Each can also be run on its own with `pnpm check:holiday` / `pnpm check:rotation` / `pnpm check:transition` / `pnpm check:repaint` / `pnpm check:code-plate` / `pnpm check:image-mode` / `pnpm check:rules` / `pnpm check:preset` / `pnpm check:ui` / `pnpm check:watchdogs` / `pnpm check:scheme` / `pnpm check:store` / `pnpm check:node`:
 
 - **`check:holiday`** — the two holiday windows, the Beijing day boundary, leap eighth months across 1900–2100, and the four gates `pickHoliday` applies.
 - **`check:rotation`** — `nextIndex` / `isRotating`: no walking off the end, shuffle never repeating the image on screen, and nothing called "rotating" with nothing to rotate.
@@ -217,7 +228,10 @@ After changing anything under `src/`, run `pnpm run bundle` again — the mounte
 - **`check:rules`** — the two decisions behind the tab strip, which live in `src/client/rules-view.ts`, plus the page structure the layout rests on.
 - **`check:preset`** — the recommended profile's retry policy and what a failed attempt holds for the next one, with both halves shown using them.
 - **`check:ui`** — both dictionaries carrying the same keys, every `dab-…` class styled, no dead entry, and every `var(--dsw-…)` published by the installed theme.
-- **`check:node`** — the built node half through its real RPC handler with `DSH_HOME` redirected and `fetch` stubbed: the holiday block, the festival art's caching and pruning, mirror fallback, the per-image color lift, the global switch effect, and the recommended profile end to end.
+- **`check:watchdogs`** — one heartbeat, entries firing on their own due time, paused while the tab is hidden, no timer left by dispose, and no module outside the entry starting its own interval.
+- **`check:scheme`** — the `data-ds-dark-theme` hand-off: the plugin only rewrites the value it wrote, hands the flag back when it drops its tokens, and repaints when the scheme moves.
+- **`check:store`** — the two decisions behind the storage cleanup, `referencedSlots` and `orphanSlots`: a picture in use is never an orphan, a stray holiday-slot file always is, and the browser half sends RULE slots rather than the whole config.
+- **`check:node`** — the built node half through its real RPC handler with `DSH_HOME` redirected and `fetch` stubbed: the holiday block, the festival art's caching and pruning, mirror fallback, the per-image color lift, the global switch effect, the store's usage report and cleanup, and the recommended profile end to end.
 
 ## FAQ
 
@@ -270,6 +284,11 @@ The effect is **Instant**, or the duration is `0` — an effect and a duration a
 
 > Only the two most recent releases are listed here; older ones live in [CHANGELOG.md](./CHANGELOG.md).
 
+### v0.9.2
+
+- **The Config tab gains an "Image storage" card** — it reports how much is cleanable and how many files that is, then offers the button; only unreferenced files go, the config and the festival art stay, and any file that resists is named.
+- **`check:store`, so there are thirteen checks now** — both READMEs had been claiming ten, having missed `check:watchdogs` and `check:scheme` since v0.8.1; they are listed again alongside the new one.
+
 ### v0.9.1
 
 - **The three wallpaper sliders are now one slider plus a picker** — the options read Image opacity / Image brightness / Image blur, the picker matches the buttons, and the hint below is gone.

package/README.zh.md

@@ -130,9 +130,20 @@
 
 - **托管在数据目录自己的形状里**（`preset/preset.json`、`preset/theme-config.json`，每张壁纸一个 `modelbg-<slot>` 文件），所以它能在 GitHub 上直接编辑，发布它就是一次 `cp`。
 - **里面每一个界面数字都是插件本来就用着的值**，所以在新装上是「加上规则和图片」；而在你已经调过的数据目录上，它把这些也一起重置 —— 它是一整份配置，不是一个补丁。
-- **先下载、后提问**，所以确认框能如实说出手里有什么 —— 而清空在下载**之后**，绝不在之前。它是面板里唯一会销毁东西的操作。
+- **先下载、后提问**，所以确认框能如实说出手里有什么 —— 而清空在下载**之后**，绝不在之前。它是面板里唯一一张会**先问再删**的卡片。
 - **少一张壁纸就整体失败并报出是哪个槽位**，而且每个文件各自重试，已经下到的部分留给下一次。
 
+### 图片存储清理
+
+「配置」页最后一张卡片：图片是按**原图**保存的，所以一次被中断的上传、一次失败的文件删除，或一次整套配置的替换，都可能在磁盘上留下不再被任何规则引用的文件 —— 而这台机器上「孤儿」正常是 **0**。卡片把用量读出来，**点清理就直接删**。
+
+- **先读、后删** —— 卡片先显示「可清理多少 MB / 几个文件」，再给出清理按钮；先删再报数的操作没人会同意。数字只描述**这一按会释放什么**：显示「正在使用 2.1 MB」是在回答一个没人问的问题，而显示「8 个文件」会让人以为八张全要删掉。
+- **只删没人引用的** —— 当前规则用到的图一个字节都不动，配置本身也不写。清理完会重新读一次，而不是用减法算，所以删除失败的文件仍然算在里面。
+- **失败会点名** —— 一个文件删不掉不会让其余六个留下来，但也不会被说成「已清理」：提示里会列出是哪几个。
+- **不问确认** —— 要删的东西按定义没有任何规则引用，而且不是从一个能用的集合里挑出来的，所以「确认」在这里只教人不看就点。安全性放在**前置判断**上：配置读不出来时按钮是灰的（见下一条），而不是先把七个文件列出来再问一遍。
+- **顺手清掉误入槽位的节日文件** —— `modelbg-h-*` 不属于任何配置（节日画在 `holiday-cache/` 里，那个槽位只读），所以它是唯一一个只有这条路径能清掉的残留。
+- **宿主是旧版时显示「读不到」而不是「0 B」** —— 两种「没有」必须长得不一样。
+
 ## 设置界面
 
 设置的**「主题」**分类下现在有三个选项卡：
@@ -141,7 +152,7 @@
 | --- | --- | --- |
 | **界面** | 全局，所有模型共用 | 主背景、左侧栏、右侧栏、卡片面板、输入框与控件、设置面板、对话文本框、轨迹页与每一个插件页的透明度 |
 | **模型背景** | 每条规则、每张图片 | 有序规则列表、实时匹配状态，以及每条规则的图片（胶片条）、**逐图布局模式 / 取景 / 主题色**，加上规则自己的透明度、亮度、模糊度与[多图轮换](#多图轮换) |
-| **配置** | — | 全局[切换效果](#切换效果全局)、整套规则的进出 —— [推荐配置](#推荐配置)与导入 / 导出（`dsh-background-by-model-theme.json`）—— 外加[节日特殊背景](#节日特殊背景)那一个开关 |
+| **配置** | — | 全局[切换效果](#切换效果全局)、整套规则的进出 —— [推荐配置](#推荐配置)与导入 / 导出（`dsh-background-by-model-theme.json`）—— 外加[节日特殊背景](#节日特殊背景)那一个开关，以及[图片存储清理](#图片存储清理) |
 
 原先的**「色彩」**选项卡已删除 —— 主题色改为规则与图片各自的属性 —— 原**「背景」**选项卡改造成**「模型背景」**。
 
@@ -184,7 +195,7 @@ npx @deepseek-ai/dsh web
 git clone https://github.com/HarmlessFunny/dsh-background-by-model.git
 cd dsh-background-by-model
 pnpm install
-pnpm test            # 构建 lib/、类型检查、跑十道检查
+pnpm test            # 构建 lib/、类型检查、跑十三道检查
 ```
 
 `pnpm run bundle` 只重建 `lib/`。两者都必须在插件能加载之前先跑一次：新 clone 出来没有 `lib/`。
@@ -206,7 +217,7 @@ pnpm test            # 构建 lib/、类型检查、跑十道检查
 
 改完 `src/` 必须重新执行 `pnpm run bundle` 才会生效 —— 挂载的 profile 加载的是 `lib/`。
 
-`pnpm test` 会构建、类型检查并跑十道校验，十道都不需要依赖、不需要转译器、也不需要浏览器。也可以单独跑：`pnpm check:holiday` / `pnpm check:rotation` / `pnpm check:transition` / `pnpm check:repaint` / `pnpm check:code-plate` / `pnpm check:image-mode` / `pnpm check:rules` / `pnpm check:preset` / `pnpm check:ui` / `pnpm check:node`：
+`pnpm test` 会构建、类型检查并跑十三道校验，十三道都不需要依赖、不需要转译器、也不需要浏览器。也可以单独跑：`pnpm check:holiday` / `pnpm check:rotation` / `pnpm check:transition` / `pnpm check:repaint` / `pnpm check:code-plate` / `pnpm check:image-mode` / `pnpm check:rules` / `pnpm check:preset` / `pnpm check:ui` / `pnpm check:watchdogs` / `pnpm check:scheme` / `pnpm check:store` / `pnpm check:node`：
 
 - **`check:holiday`** —— 两个节日窗口、北京时间的跨日边界、1900–2100 年间的闰八月，以及 `pickHoliday` 的四道闸门。
 - **`check:rotation`** —— `nextIndex` / `isRotating`：不走越界、随机不重复当前这张、没有可轮换的东西时绝不报「正在轮换」。
@@ -217,7 +228,10 @@ pnpm test            # 构建 lib/、类型检查、跑十道检查
 - **`check:rules`** —— 选项卡背后那两个住在 `src/client/rules-view.ts` 的判定，以及布局所依赖的页面结构。
 - **`check:preset`** —— 推荐配置的重试策略与失败那一次给下一次留下什么，并验证两侧真的在用它们。
 - **`check:ui`** —— 两本字典键集一致、每个 `dab-…` 类都有样式、没有死键，以及每个 `var(--dsw-…)` 都是已安装主题发布过的 token。
-- **`check:node`** —— 把构建好的 node 半边通过真实的 RPC 处理器跑一遍（`DSH_HOME` 指向临时目录、`fetch` 换成桩）：节日配置块、节日画的缓存与清理、镜像回落、逐图颜色抬升、全局切换效果，以及推荐配置的整条链路。
+- **`check:watchdogs`** —— 一条心跳、按各自到期时间触发、隐藏即暂停、dispose 不留定时器，且入口之外没有模块自己起 interval。
+- **`check:scheme`** —— `data-ds-dark-theme` 的交接：插件只改自己写的那个值、清掉 token 时一起交还标记、方案变了会重绘。
+- **`check:store`** —— 存储清理的两个判定：`referencedSlots` 与 `orphanSlots`。钉住「正在用的图不会被当成孤儿」与「节日槽位的文件必须可清」，外加浏览器半边传的是**规则槽位**而不是整份配置。
+- **`check:node`** —— 把构建好的 node 半边通过真实的 RPC 处理器跑一遍（`DSH_HOME` 指向临时目录、`fetch` 换成桩）：节日配置块、节日画的缓存与清理、镜像回落、逐图颜色抬升、全局切换效果、图片存储的用量报告与清理，以及推荐配置的整条链路。
 
 ## 常见问题
 
@@ -270,6 +284,11 @@ pnpm test            # 构建 lib/、类型检查、跑十道检查
 
 > 这里只列最近两个版本；更早的版本见 [CHANGELOG.zh.md](./CHANGELOG.zh.md)。
 
+### v0.9.2
+
+- **「配置」页多了一张「图片存储」卡片** —— 先报出可清理多少、涉及几个文件，再给你一个清理按钮；只删没有规则引用的文件，配置与节日画都不动，删不掉的文件会点名。
+- **`check:store`，于是现在十三道校验** —— 两份 README 此前一直写着「十道」，`check:watchdogs` 与 `check:scheme` 从 v0.8.1 起就没列进去，这次一并补上。
+
 ### v0.9.1
 
 - **三条壁纸滑块合并成一条，旁边用下拉框切换** —— 选项改叫图片透明度 / 图片亮度 / 图片模糊，下拉框与按钮同色，滑块下的说明文字删掉。

package/lib/client.js

@@ -1167,6 +1167,50 @@ window.__ModuleLoader__.load({
 			const parts = [d.provider, d.model].filter((s) => typeof s === "string" && s !== "");
 			return parts.length > 0 ? parts.join(" ") : null;
 		}
+		/**
+		* What the store occupies and what nothing points at — read-only.
+		*
+		* `keep` is this bundle's live slot list, which the node half unions with the config
+		* on disk (see `storeUsage`): the two are written at different moments, and the
+		* report must never call a file an orphan in the gap between an upload's bytes
+		* landing and its rule entry arriving. Sending the list can therefore only SPARE a
+		* slot, never condemn one.
+		*/
+		async function readStoreUsage(keep) {
+			const data = await rpcCall("storeUsage", { keep });
+			if (data === null || typeof data !== "object") return null;
+			const d = data;
+			return {
+				totalBytes: numberOr(d.totalBytes, 0),
+				usedBytes: numberOr(d.usedBytes, 0),
+				orphanBytes: numberOr(d.orphanBytes, 0),
+				files: numberOr(d.files, 0),
+				slots: Array.isArray(d.slots) ? d.slots.filter((s) => typeof s === "string") : [],
+				orphans: Array.isArray(d.orphans) ? d.orphans.filter((o) => o !== null && typeof o === "object" && typeof o.slot === "string").map((o) => ({
+					slot: o.slot,
+					bytes: numberOr(o.bytes, 0)
+				})) : [],
+				trusted: d.trusted === true
+			};
+		}
+		/**
+		* Delete every stored image nothing points at. The one destructive half of the
+		* pair, and it takes the same `keep` for the same reason.
+		*/
+		async function pruneOrphanImages(keep) {
+			const data = await rpcCall("pruneOrphans", { keep });
+			if (data === null || typeof data !== "object") return null;
+			const d = data;
+			return {
+				removed: Array.isArray(d.removed) ? d.removed.filter((s) => typeof s === "string") : [],
+				failed: Array.isArray(d.failed) ? d.failed.filter((s) => typeof s === "string") : [],
+				freedBytes: numberOr(d.freedBytes, 0),
+				refused: d.refused === true
+			};
+		}
+		function numberOr(value, fallback) {
+			return typeof value === "number" && isFinite(value) && value >= 0 ? value : fallback;
+		}
 		//#endregion
 		//#region src/client/utils/color.ts
 		function hsvToHsl(h, s, v) {
@@ -1927,6 +1971,13 @@ window.__ModuleLoader__.load({
 .dab-profile-ico{width:38px;height:38px;border-radius:11px;display:grid;place-items:center;margin-bottom:13px;color:var(--dsw-alias-brand-primary);background:var(--dsw-alias-bg-layer-2);background:color-mix(in srgb,var(--dsw-alias-brand-primary) 12%,transparent)}
 .dab-profile-title{font-size:14px;font-weight:650}
 .dab-profile-desc{font-size:12px;color:var(--dsw-alias-label-tertiary);line-height:1.55;margin:5px 0 15px}
+/* The image store's three numbers. A row of VALUES with a caption under each,
+   not a sentence: they are read as a measurement ("how much is orphaned"), and a
+   sentence makes the reader hunt for the one number that matters. */
+.dab-store-stats{display:flex;gap:16px;margin:2px 0 14px}
+.dab-store-stat{display:flex;flex-direction:column;gap:2px;min-width:0}
+.dab-store-stat-v{font-size:14px;font-weight:650;font-family:var(--dab-mono);letter-spacing:.01em;color:var(--dsw-alias-label-primary)}
+.dab-store-stat-k{font-size:11px;color:var(--dsw-alias-label-tertiary);white-space:nowrap}
 .dab-footer{margin-top:6px;padding:14px 4px 0;border-top:1px solid var(--dsw-alias-border-l2);display:flex;align-items:center;justify-content:space-between;font-size:11px;color:var(--dsw-alias-label-tertiary)}
 .dab-footer-mono{font-family:var(--dab-mono);letter-spacing:.02em}
 /* Same reset as the brand: the package name links to the repository, and the
@@ -4248,6 +4299,11 @@ window.__ModuleLoader__.load({
 			className,
 			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M7.2 1.8l1.2 3.1 3.1 1.2-3.1 1.2-1.2 3.1-1.2-3.1L2.9 6.1 6 4.9l1.2-3.1z" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M12 10.5l.5 1.2 1.2.5-1.2.5-.5 1.2-.5-1.2-1.2-.5 1.2-.5.5-1.2z" })]
 		});
+		const RefreshIcon = ({ size, className }) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Glyph, {
+			size,
+			className,
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M13.2 8A5.2 5.2 0 1 1 11.5 4.2" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", { d: "M13.4 1.8v2.9h-2.9" })]
+		});
 		const DownloadIcon = ({ size, className }) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(Glyph, {
 			size,
 			className,
@@ -4767,6 +4823,18 @@ window.__ModuleLoader__.load({
 			recFailTooLarge: "这份推荐配置体积过大，未做任何改动",
 			recFailImage: "这张壁纸没拿到（素材库里缺这个文件）：",
 			recFailApply: "未能写入推荐配置，你原来的配置没有被改动",
+			storeCardTitle: "图片存储",
+			storeCardDesc: "因意外导致的孤儿图片这里可以清掉",
+			storeOrphans: "可清理",
+			storeFiles: "个可删文件",
+			storeReading: "正在读取…",
+			storeUnknown: "读不到存储信息（宿主进程可能是旧版插件，重启 DSH 后可用）",
+			storeCleanNone: "没有多余的文件",
+			storeClean: "清理",
+			storeDoneFreed: "已清理，释放",
+			storePartial: "有些文件没能删除：",
+			storeRefused: "配置文件读不出来（theme-config.json 解析失败），现在分不清哪些图片还在用，所以没有删除任何东西。修好或删掉那个文件后重启 DSH 再试",
+			storeRefresh: "重新读取",
 			footerTag: "按模型换背景插件",
 			repoLink: "在 GitHub 上打开仓库",
 			holidayTitle: "节日特殊背景",
@@ -4938,6 +5006,18 @@ window.__ModuleLoader__.load({
 			recFailTooLarge: "The recommended profile is too large. Nothing was changed.",
 			recFailImage: "Could not fetch this wallpaper — the asset host has no such file:",
 			recFailApply: "Could not write the recommended profile — your own is untouched",
+			storeCardTitle: "Image storage",
+			storeCardDesc: "Orphaned image files left behind by an accident can be cleared here",
+			storeOrphans: "Cleanable",
+			storeFiles: "deletable files",
+			storeReading: "Reading…",
+			storeUnknown: "Could not read the store — the host process may be an older build; restart DSH",
+			storeCleanNone: "Nothing to clean up",
+			storeClean: "Clean up",
+			storeDoneFreed: "Cleaned up, freed",
+			storePartial: "Some files could not be deleted: ",
+			storeRefused: "The config file could not be read (theme-config.json does not parse), so nothing on disk can be told apart from an orphan. Nothing was deleted — fix or remove that file and restart DSH",
+			storeRefresh: "Refresh",
 			footerTag: "Per-model wallpaper plugin",
 			repoLink: "Open the repository on GitHub",
 			holidayTitle: "Holiday backgrounds",
@@ -7316,6 +7396,41 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region src/format.ts
+		/**
+		* Byte counts as a person reads them — the only two sentences this plugin says
+		* about size, in one place so their difference cannot be an accident.
+		*
+		* They are NOT the same question, which is why there are two:
+		*
+		*   - a download's size describes ONE file that just arrived;
+		*   - a storage figure describes a total that is routinely zero.
+		*
+		* The floor below is right for the first and wrong for the second, and the wrong
+		* answer is not a crash: it is a card that offers to clean up 1 KB and a button
+		* that refuses to, on a store where there is nothing to clean. Neither number is
+		* ever deleted or written — these are display strings — but a maintenance panel
+		* whose numbers disagree with its own button is worse than no panel.
+		*/
+		/**
+		* Size of one download, at the precision a person reads it at.
+		*
+		* Floors at 1 KB on purpose: it is shown beside a file that just arrived, and
+		* "0 KB" beside a picture that downloaded fine reads as a failure.
+		*/
+		const fmtBytes = (n) => n >= 1048576 ? `${(n / 1024 / 1024).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`;
+		/**
+		* A figure on the storage card, where zero is a real and — on a tidy store — the
+		* usual answer.
+		*
+		* `fmtBytes` would print "1 KB" for it, so the card claimed 1 KB of waste while
+		* the clean button sat disabled (its condition is `orphanBytes === 0`, which was
+		* true all along). Rounding remains conservative in the other direction: a real
+		* orphan is never allowed to read as zero, because a number that cannot go down
+		* is exactly the complaint this feature exists to answer.
+		*/
+		const fmtStoreBytes = (n) => n > 0 ? fmtBytes(n) : "0 KB";
+		//#endregion
 		//#region src/client/components/pages/ProfilePage.tsx
 		/** Chip labels, keyed by the value they set — so no chip can be built from a
 		*  value the schema does not accept, and `check:ui` still sees every key used. */
@@ -7359,8 +7474,6 @@ window.__ModuleLoader__.load({
 			"too many images": "recFailTooMany",
 			"too large": "recFailTooLarge"
 		};
-		/** Size of a download, at the precision a person reads it at. */
-		const fmtBytes = (n) => n >= 1048576 ? `${(n / 1024 / 1024).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`;
 		function ProfilePage({ p, notify }) {
 			const { t, exportTheme, importTheme, setTransition } = p;
 			const importRef = (0, react.useRef)(null);
@@ -7463,6 +7576,46 @@ window.__ModuleLoader__.load({
 				setPending(null);
 				notify(ok ? t("recDone") : t("recFailApply"), ok);
 			};
+			const [usage, setUsage] = (0, react.useState)(null);
+			/** Distinguishes "not asked yet" from "asked, and the host cannot answer". */
+			const [usageRead, setUsageRead] = (0, react.useState)(false);
+			const [storeBusy, setStoreBusy] = (0, react.useState)(false);
+			const refreshStore = async () => {
+				const next = await p.readStoreUsage();
+				setUsage(next);
+				setUsageRead(true);
+			};
+			(0, react.useEffect)(() => {
+				let live = true;
+				(async () => {
+					const next = await p.readStoreUsage();
+					if (!live) return;
+					setUsage(next);
+					setUsageRead(true);
+				})();
+				return () => {
+					live = false;
+				};
+			}, [store.rulesRev]);
+			const onClean = async () => {
+				setStoreBusy(true);
+				const res = await p.pruneOrphanImages();
+				await refreshStore();
+				setStoreBusy(false);
+				if (res === null) {
+					notify(t("storeUnknown"), false);
+					return;
+				}
+				if (res.refused) {
+					notify(t("storeRefused"), false);
+					return;
+				}
+				if (res.failed.length > 0) {
+					notify(`${t("storePartial")}${res.failed.join(", ")}`, false);
+					return;
+				}
+				notify(res.removed.length === 0 ? t("storeCleanNone") : `${t("storeDoneFreed")} ${fmtStoreBytes(res.freedBytes)}`, true);
+			};
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
 				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("header", {
 					className: "dab-head dab-rise",
@@ -7745,6 +7898,74 @@ window.__ModuleLoader__.load({
 									}
 								})
 							]
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
+							className: "dab-card dab-card-hover",
+							children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+									className: "dab-profile-ico",
+									children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(TrashIcon, { size: 17 })
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+									className: "dab-profile-title",
+									children: t("storeCardTitle")
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+									className: "dab-profile-desc",
+									children: t("storeCardDesc")
+								}),
+								usage === null ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+									className: "dab-hint",
+									style: { marginBottom: 12 },
+									children: usageRead ? t("storeUnknown") : t("storeReading")
+								}) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									className: "dab-store-stats",
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										className: "dab-store-stat",
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+											className: "dab-store-stat-v",
+											children: fmtStoreBytes(usage.orphanBytes)
+										}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+											className: "dab-store-stat-k",
+											children: t("storeOrphans")
+										})]
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										className: "dab-store-stat",
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+											className: "dab-store-stat-v",
+											children: usage.orphans.length
+										}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+											className: "dab-store-stat-k",
+											children: t("storeFiles")
+										})]
+									})]
+								}), usage.trusted ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+									className: "dab-hint dab-stale",
+									style: { marginBottom: 12 },
+									children: t("storeRefused")
+								})] }),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									style: {
+										display: "flex",
+										gap: 8,
+										flexWrap: "wrap"
+									},
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+										type: "button",
+										className: "dab-btn",
+										disabled: storeBusy || usage === null || usage.orphanBytes === 0 || !usage.trusted,
+										title: usage !== null && !usage.trusted ? t("storeRefused") : usage !== null && usage.orphanBytes === 0 ? t("storeCleanNone") : t("storeClean"),
+										onClick: () => void onClean(),
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(TrashIcon, { size: 14 }), t("storeClean")]
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+										type: "button",
+										className: "dab-btn dab-btn-ghost",
+										disabled: storeBusy,
+										onClick: () => void refreshStore(),
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(RefreshIcon, { size: 14 }), t("storeRefresh")]
+									})]
+								})
+							]
 						})
 					]
 				}),
@@ -8648,6 +8869,12 @@ window.__ModuleLoader__.load({
 					applyRecommended: async (preset) => {
 						if (!canWriteConfig()) return false;
 						return await applyThemeFile({ applyActive }, preset, true);
+					},
+					readStoreUsage: () => readStoreUsage(cfg.rules.flatMap(ruleSlots)),
+					pruneOrphanImages: async () => {
+						const res = await pruneOrphanImages(cfg.rules.flatMap(ruleSlots));
+						for (const slot of res?.removed ?? []) setImage(slot, null);
+						return res;
 					}
 				};
 			};

package/lib/index.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
 //#region src/holiday.ts
 const HOLIDAYS = [{
@@ -464,6 +464,41 @@ function presetRetryDelayMs(failedAttempt) {
 	return 400 * 2 ** Math.max(0, failedAttempt - 1);
 }
 //#endregion
+//#region src/store.ts
+/**
+* Every slot the config still points at, in first-seen order and without repeats.
+*
+* Rules only. A holiday's slot is deliberately NOT included: its art lives in
+* `holiday-cache/`, it is never written to the slot namespace, and a
+* `modelbg-h-*` file therefore cannot belong to anything (see the read-only
+* invariant in MAINTAINING §7.1). Counting the slot as referenced would make such
+* a file permanently unprunable — the one residue this cleanup could never clear.
+*/
+function referencedSlots(rules) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const rule of rules) for (const image of rule.images) {
+		if (typeof image.slot !== "string" || seen.has(image.slot)) continue;
+		seen.add(image.slot);
+		out.push(image.slot);
+	}
+	return out;
+}
+/**
+* The files whose slot appears in neither `referenced` nor `kept`.
+*
+* `stored` order is preserved because the caller deletes in it and reports what it
+* removed in that order, which is the only order the user has ever seen these files
+* in. `kept` exists for one reason: the browser half's live config can be a few
+* hundred milliseconds ahead of its own write to disk (a slot is written, then the
+* config that names it), and an image whose bytes have landed but whose rule entry
+* has not must not be deleted in that window.
+*/
+function orphanSlots(stored, referenced, kept = []) {
+	const live = /* @__PURE__ */ new Set([...referenced, ...kept]);
+	return stored.filter((slot) => !live.has(slot));
+}
+//#endregion
 //#region src/index.ts
 /**
 * Node half of dsh-background-by-model: file-backed rule persistence.
@@ -674,6 +709,61 @@ async function readConfig() {
 	}
 	return normalizeConfig(await migrateLegacy(raw));
 }
+/**
+* The config, plus whether it is safe to decide what the store still owns from it.
+*
+* `readConfig` deliberately swallows a corrupt file and answers with defaults —
+* right for painting (a broken file must not leave a blank panel) and WRONG for
+* the cleanup, which would then see zero referenced slots and treat every image on
+* disk as an orphan. That is the one way this feature could delete a user's whole
+* wallpaper collection, so the two cases are told apart here and the sweep refuses
+* rather than guesses:
+*
+*   - no file at all → trusted. A fresh store has images only if something wrote
+*     them, and nothing did;
+*   - a file that parses to an object → trusted (its rules are what they say);
+*   - a file that is there but does not parse, or is not an object → NOT trusted.
+*
+* A config whose `rules` are missing entirely is trusted: `normalizeConfig` seeds
+* one blank rule for that case, which owns no slot, and the sanitizer's answer is
+* exactly what a reload would paint.
+*
+* The untrusted branch deliberately does NOT go through `migrateLegacy`: that one
+* WRITES a repaired config back to disk for the shapes earlier releases left
+* behind, and running it here would turn "refuse to delete" into "quietly rewrite
+* whatever the user's broken file said, then delete against the rewrite". The
+* display answer for an unreadable file is the sanitizer's defaults, computed
+* without touching the disk.
+*/
+async function readConfigForSweep() {
+	await ensureDir();
+	let text;
+	try {
+		text = await readFile(configPath(), "utf8");
+	} catch {
+		return {
+			config: await readConfig(),
+			trusted: true
+		};
+	}
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch {
+		return {
+			config: normalizeConfig({}),
+			trusted: false
+		};
+	}
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {
+		config: normalizeConfig({}),
+		trusted: false
+	};
+	return {
+		config: normalizeConfig(await migrateLegacy(raw)),
+		trusted: true
+	};
+}
 const LEGACY_CONFIG_KEYS = /* @__PURE__ */ new Set([
 	"color",
 	"bgMode",
@@ -1159,6 +1249,106 @@ async function resetStore() {
 	return ok;
 }
 /**
+* What the image store occupies, and which of it nothing points at any more.
+*
+* Read-only: it reports, it never deletes. Splitting the two is what lets the panel
+* show a number before asking, and it is also the only honest way to answer "how
+* much would this free" — a cleanup whose size is announced AFTER the fact is a
+* cleanup nobody agrees to.
+*
+* `keep` is the browser half's own slot list. It is unioned with the config ON DISK
+* rather than replacing it because the two are not written at the same moment: an
+* upload writes the bytes first and the config that names them a moment later, so a
+* read landing in between would see a file the store is about to legitimately own.
+* The union can only ever make the report SMALLER (a slot is spared), which is the
+* safe direction for something whose answer is "delete these files".
+*
+* A file that cannot be stat'd is still listed, at 0 bytes: it exists as far as
+* `readdir` is concerned, and hiding it would leave a residue the panel claims is
+* not there.
+*
+* `trusted` is false when the config file on disk is there but unreadable (see
+* `readConfigForSweep`). The numbers are then still reported — the user asked what
+* the store occupies, and that question has an answer — but the caller must not
+* delete: with no trustworthy rule list, EVERY file would look like an orphan.
+*/
+async function storeUsage(keep) {
+	const stored = await listSlots();
+	const { config, trusted } = await readConfigForSweep();
+	const orphans = orphanSlots(stored, referencedSlots(config.rules), keep);
+	const sizes = /* @__PURE__ */ new Map();
+	let totalBytes = 0;
+	for (const slot of stored) {
+		let bytes = 0;
+		try {
+			bytes = (await stat(imagePath(slot))).size;
+		} catch {}
+		sizes.set(slot, bytes);
+		totalBytes += bytes;
+	}
+	let orphanBytes = 0;
+	for (const slot of orphans) orphanBytes += sizes.get(slot) ?? 0;
+	return {
+		totalBytes,
+		usedBytes: totalBytes - orphanBytes,
+		orphanBytes,
+		files: stored.length,
+		slots: stored,
+		orphans: orphans.map((slot) => ({
+			slot,
+			bytes: sizes.get(slot) ?? 0
+		})),
+		trusted
+	};
+}
+/**
+* Delete every stored image nothing points at, and report what was removed.
+*
+* `keep` is the caller's live slot list, with the same meaning and the same
+* union-with-disk rule as `storeUsage`. The answer carries the freed byte count so
+* the panel can say what happened, and `failed` names the slots that resisted —
+* a cleanup that removed six of seven files and said "done" would leave the user
+* with a number that never goes down and no way to learn why.
+*
+* Failures are per file and never abort the sweep: one locked file must not protect
+* the other six. Nothing else in the store is touched — the config, the festival art
+* and the released generations under `holiday-cache/` are all outside this walk.
+*
+* REFUSES on an unreadable config (`trusted: false`): every file would look
+* unreferenced, and this is the one operation in the plugin that could delete a
+* whole wallpaper collection in a single press. A refusal costs a number on a card;
+* guessing costs the user their pictures.
+*/
+async function pruneOrphans(keep) {
+	const usage = await storeUsage(keep);
+	if (!usage.trusted) {
+		console.warn("dsh-background-by-model: refusing to prune — \"theme-config.json\" is unreadable, so nothing on disk can be told apart from an orphan");
+		return {
+			removed: [],
+			failed: [],
+			freedBytes: 0,
+			refused: true
+		};
+	}
+	const removed = [];
+	const failed = [];
+	let freedBytes = 0;
+	for (const entry of usage.orphans) try {
+		await rm(imagePath(entry.slot), { force: true });
+		removed.push(entry.slot);
+		freedBytes += entry.bytes;
+	} catch (e) {
+		failed.push(entry.slot);
+		console.warn(`dsh-background-by-model: failed to remove the orphaned image for slot "${entry.slot}"`, e);
+	}
+	return {
+		removed,
+		failed,
+		freedBytes,
+		refused: false
+	};
+}
+/**
 * Download an image from a network URL into one slot (replacing its bytes).
 * Returns { ok, dataUrl?, error? }; never throws.
 */
@@ -1277,6 +1467,8 @@ async function handleRpcMethod(ctx, endpoint, payload) {
 	const method = endpoint.startsWith(`${RPC_NS}/`) ? endpoint.slice(21) : "";
 	const rawSlot = payload?.slot;
 	const slot = typeof rawSlot === "string" && SLOT_RE.test(rawSlot) ? rawSlot : null;
+	const rawKeep = payload?.keep;
+	const keep = Array.isArray(rawKeep) ? rawKeep.filter((s) => typeof s === "string" && SLOT_RE.test(s)) : [];
 	try {
 		switch (method) {
 			case "read": return {
@@ -1350,6 +1542,14 @@ async function handleRpcMethod(ctx, endpoint, payload) {
 				ok: true,
 				value: await resetStore()
 			};
+			case "storeUsage": return {
+				ok: true,
+				value: await storeUsage(keep)
+			};
+			case "pruneOrphans": return {
+				ok: true,
+				value: await pruneOrphans(keep)
+			};
 			case "defaultModel": return {
 				ok: true,
 				value: defaultModel(ctx)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-background-by-model",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Appearance plugin for DeepSeek Harness: an ordered list of model rules, each carrying its own wallpapers — every image with its own framing and theme color — plus layout mode, opacity, brightness and blur; the background follows the model you switch to, and a rule can rotate through several images on its own rhythm.",
   "keywords": [
     "deepseek-harness",
@@ -65,8 +65,9 @@
     "check:ui": "node scripts/ui-strings-check.ts",
     "check:watchdogs": "node scripts/watchdogs-check.ts",
     "check:scheme": "node scripts/scheme-check.ts",
+    "check:store": "node scripts/store-check.ts",
     "check:node": "node scripts/node-half-check.mjs",
-    "test": "tsdown && tsc -p tsconfig.json && node scripts/holiday-check.ts && node scripts/rotation-check.ts && node scripts/transition-check.ts && node scripts/repaint-check.ts && node scripts/code-plate-check.ts && node scripts/image-mode-check.ts && node scripts/rules-view-check.ts && node scripts/preset-check.ts && node scripts/ui-strings-check.ts && node scripts/watchdogs-check.ts && node scripts/scheme-check.ts && node scripts/node-half-check.mjs"
+    "test": "tsdown && tsc -p tsconfig.json && node scripts/holiday-check.ts && node scripts/rotation-check.ts && node scripts/transition-check.ts && node scripts/repaint-check.ts && node scripts/code-plate-check.ts && node scripts/image-mode-check.ts && node scripts/rules-view-check.ts && node scripts/preset-check.ts && node scripts/ui-strings-check.ts && node scripts/watchdogs-check.ts && node scripts/scheme-check.ts && node scripts/store-check.ts && node scripts/node-half-check.mjs"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-home-paths": ">=0.2.1-alpha.2",