dsh-background-by-model 0.9.1 → 0.10.0

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 = [{
@@ -108,6 +108,28 @@ const DEFAULT_TRANSITION = {
 	easing: "ease",
 	durationMs: 320
 };
+/**
+* One image entry for a place that CREATES a picture rather than reads one back
+* (a fresh holiday, and every upload in the panel).
+*
+* The two effects whose neutral value is also the shipped default are written
+* explicitly (`opacity`, `blur`), even though `normalizeImage` would default them:
+* the read-time lifts key off the ABSENCE of a key, so an entry created without one
+* would come back as "written before this field existed" and inherit whatever the
+* rule happened to carry. `brightness` is the one field whose absence is meaningful
+* (see `BgImage.brightness`), so it is left out — "untouched" is exactly what a new
+* picture is.
+*/
+function defaultImage(slot, color = null, bgMode = "fit") {
+	return {
+		slot,
+		bgMode,
+		bgState: { ...DEFAULT_BG_STATE },
+		color,
+		opacity: 1,
+		blur: 0
+	};
+}
 const DEFAULT_CHAT_TEXT_OPACITY = .35;
 const DEFAULT_TRAJECTORY_OPACITY = .73;
 const DEFAULT_RIGHTBAR_OPACITY = .45;
@@ -156,18 +178,10 @@ function defaultHolidayRule(def) {
 	const color = hexToHsl(def.color);
 	return {
 		id: def.id,
-		images: [{
-			slot: def.slot,
-			bgMode: "fill",
-			bgState: { ...DEFAULT_BG_STATE },
-			color
-		}],
+		images: [defaultImage(def.slot, color, "fill")],
 		match: "",
 		enabled: true,
 		color,
-		wallpaperOpacity: 1,
-		brightness: 100,
-		blur: 0,
 		rotate: defaultRotation()
 	};
 }
@@ -187,9 +201,6 @@ function blankRule(id) {
 		match: "",
 		enabled: true,
 		color: null,
-		wallpaperOpacity: 1,
-		brightness: 100,
-		blur: 0,
 		rotate: defaultRotation()
 	};
 }
@@ -276,28 +287,41 @@ function normalizeTransition(raw, legacyMs) {
 		durationMs: clamp(t.durationMs, 0, TRANSITION_MAX_MS, fallback)
 	};
 }
+/** The inherit block for a caller that has no rule-level values at all. */
+const DEFAULT_IMAGE_INHERIT = {
+	color: null,
+	opacity: 1,
+	brightness: void 0,
+	blur: 0
+};
 /**
 * Coerce one persisted image entry, or null when it lacks a usable slot.
 *
-* `inherit` (the RULE's colour) is applied only to an entry with no `color` KEY at
-* all — the shape written before per-image colours, where the rule's colour was the
-* only one there was. The key's PRESENCE is the whole distinction: `color: null` is
-* a deliberate "follow the system theme" and must not be re-inherited on every load.
+* `inherit` is the rule-level block this entry may take its values from, and each
+* field is lifted ONLY when the entry has no key of its own — that absence is the
+* whole signal. `color: null` is a deliberate "follow the system theme" and must
+* not be re-inherited on every load; `brightness` keeps its key absent when neither
+* side ever named one, so an upgrade never writes a default nobody chose.
 *
 * `inheritMode` is the same one-shot lift for the layout mode. It is the caller's to
 * resolve because the callers answer differently: a user rule passes the mode its
 * config carried at the RULE level (schema 5), a holiday passes its own `fill`. An
 * entry that HAS a `bgMode` key keeps it, even when it equals the default.
 */
-function normalizeImage(raw, inherit = null, inheritMode = "fit") {
+function normalizeImage(raw, inherit = DEFAULT_IMAGE_INHERIT, inheritMode = "fit") {
 	const i = raw ?? {};
 	if (typeof i.slot !== "string" || !SLOT_RE.test(i.slot)) return null;
-	return {
+	const image = {
 		slot: i.slot,
 		bgMode: BG_MODES.includes(i.bgMode) ? i.bgMode : inheritMode,
 		bgState: normalizeBgState(i.bgState),
-		color: hasOwn(i, "color") ? normalizeHsl(i.color) : inherit
+		color: hasOwn(i, "color") ? normalizeHsl(i.color) : inherit.color,
+		opacity: clamp01(i.opacity, inherit.opacity),
+		blur: clamp(i.blur, 0, 60, inherit.blur)
 	};
+	const brightness = i.brightness === void 0 ? inherit.brightness : clamp(i.brightness, 0, 200, 100);
+	if (brightness !== void 0) image.brightness = brightness;
+	return image;
 }
 /**
 * Coerce one persisted rule, or null when it names no image ANYWHERE.
@@ -322,38 +346,45 @@ function normalizeRule(raw) {
 	if (id === null) return null;
 	const color = normalizeHsl(r.color);
 	const mode = BG_MODES.includes(r.bgMode) ? r.bgMode : "fit";
+	const inherit = {
+		color,
+		opacity: clamp01(r.wallpaperOpacity, 1),
+		brightness: r.brightness === void 0 ? void 0 : clamp(r.brightness, 0, 200, 100),
+		blur: clamp(r.blur, 0, 60, 0)
+	};
 	const images = [];
 	const seen = /* @__PURE__ */ new Set();
 	const hadList = Array.isArray(r.images);
 	if (hadList) for (const entry of r.images) {
-		const image = normalizeImage(entry, color, mode);
+		const image = normalizeImage(entry, inherit, mode);
 		if (image === null || seen.has(image.slot)) continue;
 		seen.add(image.slot);
 		images.push(image);
 	}
 	const legacySlot = typeof r.slot === "string" && SLOT_RE.test(r.slot) ? r.slot : null;
-	if (images.length === 0 && legacySlot !== null) images.push({
-		slot: legacySlot,
-		bgMode: mode,
-		bgState: normalizeBgState(r.bgState),
-		color
-	});
+	if (images.length === 0 && legacySlot !== null) {
+		const image = {
+			slot: legacySlot,
+			bgMode: mode,
+			bgState: normalizeBgState(r.bgState),
+			color,
+			opacity: inherit.opacity,
+			blur: inherit.blur
+		};
+		if (inherit.brightness !== void 0) image.brightness = inherit.brightness;
+		images.push(image);
+	}
 	if (images.length === 0 && !hadList) return null;
 	const rotate = normalizeRotation(r.rotate);
 	if (images.length < 2) rotate.enabled = false;
-	const brightness = r.brightness === void 0 ? void 0 : clamp(r.brightness, 0, 200, 100);
-	const rule = {
+	return {
 		id,
 		images,
 		match: typeof r.match === "string" ? r.match : "",
 		enabled: r.enabled !== false,
 		color,
-		wallpaperOpacity: clamp01(r.wallpaperOpacity, 1),
-		blur: clamp(r.blur, 0, 60, 0),
 		rotate
 	};
-	if (brightness !== void 0) rule.brightness = brightness;
-	return rule;
 }
 /**
 * Coerce one persisted holiday entry.
@@ -370,17 +401,29 @@ function normalizeHolidayRule(def, raw) {
 	return {
 		...base,
 		enabled: r.enabled !== false,
-		wallpaperOpacity: clamp01(r.wallpaperOpacity, base.wallpaperOpacity),
-		brightness: clamp(r.brightness, 0, 200, base.brightness ?? 100),
-		blur: clamp(r.blur, 0, 60, base.blur),
-		images: base.images.map((image) => ({
-			slot: image.slot,
-			bgMode: image.bgMode,
-			bgState: normalizeBgState(r.images?.[0]?.bgState ?? r.bgState),
-			color: image.color
-		}))
+		images: base.images.map((image) => {
+			const stored = r.images?.[0];
+			const merged = {
+				slot: image.slot,
+				bgMode: image.bgMode,
+				bgState: normalizeBgState(stored?.bgState ?? r.bgState),
+				color: image.color,
+				opacity: clamp01(stored?.opacity ?? legacyWallpaperOpacity(r.wallpaperOpacity), image.opacity),
+				blur: clamp(stored?.blur ?? r.blur, 0, 60, image.blur)
+			};
+			const brightness = stored?.brightness === void 0 ? r.brightness === void 0 ? void 0 : clamp(r.brightness, 0, 200, 100) : clamp(stored.brightness, 0, 200, 100);
+			if (brightness !== void 0) merged.brightness = brightness;
+			return merged;
+		})
 	};
 }
+/**
+* The rule-level opacity a schema-9 holiday entry carried, or `undefined` so the
+* caller can tell "absent" from "set to 1" and leave `clamp01` its default.
+*/
+function legacyWallpaperOpacity(raw) {
+	return typeof raw === "number" && isFinite(raw) ? raw : void 0;
+}
 /** Coerce the whole holiday block; unknown ids are dropped, missing ones defaulted. */
 function normalizeHolidays(raw) {
 	const r = raw ?? {};
@@ -464,6 +507,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.
@@ -473,8 +551,9 @@ function presetRetryDelayMs(failedAttempt) {
 * `/api`, which slash commands own).
 *
 *   theme-config.json     the ordered rule list + the global interface settings
-*   modelbg-<slot>        one background image per rule (raw bytes, no extension;
-*                         the MIME is sniffed from the magic bytes when served)
+*   theme-config.json.bak the last config that parsed, rotated in before every save
+*   modelbg-<slot>        one background image (raw bytes, no extension; the MIME is
+*                         sniffed from the magic bytes when served)
 *   holiday-cache/<tag>/  festival art downloaded from the CDN, one directory per
 *                         pinned release, deliberately NOT in the slot namespace
 *
@@ -486,6 +565,20 @@ const name = "dsh-background-by-model";
 const inject = ["connection", "webServer"];
 const DATA_DIR = ".dsh-background-by-model-data";
 const CONFIG_FILE = "theme-config.json";
+/**
+* The last config that was known to parse, kept beside the live one.
+*
+* A config file is the whole rule list, and it is rewritten on every edit. Writing
+* it in place meant a crash, a full disk or a pulled power cable could leave half a
+* JSON document behind — which `readConfig` greets by silently falling back to the
+* defaults, so the next slider drag would persist those defaults over the ruined
+* file and the original rules were gone for good. Two pieces fix that, and they are
+* one feature: the write is atomic (temp + rename), and the previous good file is
+* rotated to `.bak` before it is replaced, so even a lost file has a copy.
+*/
+const CONFIG_BACKUP = "theme-config.json.bak";
+/** Suffix of the in-flight write. Deliberately outside `listSlots`' `modelbg-` prefix. */
+const CONFIG_TEMP = ".tmp";
 const IMAGE_PREFIX = "modelbg-";
 const LEGACY_WALLPAPER = "wallpaper.jpg";
 const LEGACY_FILES = [
@@ -587,6 +680,8 @@ const PRESET_IMAGE_COUNT_MAX = 64;
 const PRESET_FETCH_TIMEOUT = 6e4;
 const dataDir = () => dshHomePath(DATA_DIR);
 const configPath = () => dshHomePath(DATA_DIR, CONFIG_FILE);
+const configBackupPath = () => dshHomePath(DATA_DIR, CONFIG_BACKUP);
+const configTempPath = () => dshHomePath(DATA_DIR, `${CONFIG_FILE}${CONFIG_TEMP}`);
 const legacyWallpaperPath = () => dshHomePath(DATA_DIR, LEGACY_WALLPAPER);
 const imagePath = (slot) => dshHomePath(DATA_DIR, `${IMAGE_PREFIX}${slot}`);
 const holidayCachePath = (asset) => dshHomePath(DATA_DIR, HOLIDAY_CACHE_DIR, HOLIDAY_ASSETS_REF, asset);
@@ -635,14 +730,15 @@ async function migrateLegacy(raw) {
 			images: [{
 				slot: "m1",
 				bgMode: typeof r.bgMode === "string" ? r.bgMode : "fit",
-				bgState: r.bgState ?? {}
+				bgState: r.bgState ?? {},
+				color: Array.isArray(r.color) ? r.color : null,
+				opacity: typeof r.wallpaperOpacity === "number" ? r.wallpaperOpacity : 1,
+				...typeof r.brightness === "number" ? { brightness: r.brightness } : {},
+				blur: typeof r.blur === "number" ? r.blur : 0
 			}],
 			match: "",
 			enabled: true,
-			color: Array.isArray(r.color) ? r.color : null,
-			wallpaperOpacity: typeof r.wallpaperOpacity === "number" ? r.wallpaperOpacity : 1,
-			brightness: typeof r.brightness === "number" ? r.brightness : 100,
-			blur: typeof r.blur === "number" ? r.blur : 0
+			color: Array.isArray(r.color) ? r.color : null
 		}],
 		opacities: r.opacities,
 		settingsOpacity: r.settingsOpacity,
@@ -651,7 +747,7 @@ async function migrateLegacy(raw) {
 		rightbarOpacity: r.rightbarOpacity
 	};
 	try {
-		await writeFile(configPath(), JSON.stringify(next, null, 2), "utf8");
+		await writeConfigFile(serializeConfig(next));
 	} catch (e) {
 		console.warn("dsh-background-by-model: could not rewrite the migrated config", e);
 	}
@@ -664,16 +760,183 @@ async function ensureDir() {
 		console.warn(`dsh-background-by-model: cannot create data dir "${dataDir()}"`, e);
 	}
 }
+/** The exact bytes a config file should hold. */
+function serializeConfig(config) {
+	return JSON.stringify(config, null, 2);
+}
+/**
+* Whether a string is a config this build would accept: JSON, and an object.
+*
+* Deliberately looser than `normalizeConfig` (which accepts anything and defaults
+* every field): this is the test for "is there something worth keeping", so a
+* schema-3 file and a hand-edited one both count. What it rejects is the two ways a
+* write can be interrupted — half a document, and an empty one.
+*/
+function parsesAsConfig(text) {
+	try {
+		const value = JSON.parse(text);
+		return value !== null && typeof value === "object" && !Array.isArray(value);
+	} catch {
+		return false;
+	}
+}
+/**
+* Write one config file so that no reader can ever see a partial document, keeping
+* the previous good one as `.bak`.
+*
+* Two steps, in this order, because the order is what makes the copy worth having:
+*
+*   1. the file on disk NOW is copied to `theme-config.json.bak` — but only when it
+*      parses. A corrupted live file must never overwrite the last good backup, or
+*      the first write after the corruption would also destroy the copy that could
+*      have replaced it;
+*   2. the new bytes go to a temp name and are RENAMED over the live path. A rename
+*      is atomic within one directory, so a crash either leaves the old file or the
+*      new one — never half of either.
+*
+* The rename is not `writeFile` for the same reason: writing in place truncates
+* first, and a crash between the truncation and the last byte is exactly the state
+* that used to eat a rule list.
+*/
+async function writeConfigFile(text) {
+	await ensureDir();
+	const target = configPath();
+	try {
+		const current = await readFile(target, "utf8");
+		if (parsesAsConfig(current)) {
+			const backupTemp = `${configBackupPath()}${CONFIG_TEMP}`;
+			await writeFile(backupTemp, current, "utf8");
+			await renameOver(backupTemp, configBackupPath());
+		}
+	} catch {}
+	const temp = configTempPath();
+	await writeFile(temp, text, "utf8");
+	await renameOver(temp, target);
+}
+/**
+* `rename` over an existing file, which replaces it atomically on POSIX.
+*
+* Windows refuses to rename onto a name that exists (EEXIST / EPERM), so the one
+* platform that cannot do this in one step gets a two-step fallback — and the
+* difference matters: unlinking first leaves a window with NO file, which is the
+* state this whole function exists to avoid, so on POSIX the unlink must never be
+* attempted. The fallback is only reached when the rename itself said the target is
+* in the way, which is exactly the Windows case.
+*/
+async function renameOver(from, to) {
+	try {
+		await rename(from, to);
+	} catch (e) {
+		const code = e?.code;
+		if (code !== "EEXIST" && code !== "EPERM" && code !== "ENOTEMPTY") throw e;
+		await rm(to, { force: true });
+		await rename(from, to);
+	}
+}
+/**
+* The last good config that can be restored, as raw text — or null when there is
+* none.
+*
+* Two candidates, in order of authority: the live file (when it parses, which is
+* the ordinary case and costs one read) and the `.bak`. The backup is only
+* consulted for a live file that is missing or corrupt, so a half-written document
+* from an interrupted save is answered with the copy rather than with the shipped
+* defaults — which is the difference between "your rules are back" and "your rules
+* were never there".
+*/
+async function readConfigFile() {
+	try {
+		const text = await readFile(configPath(), "utf8");
+		if (parsesAsConfig(text)) return {
+			text,
+			source: "live"
+		};
+	} catch {}
+	try {
+		const text = await readFile(configBackupPath(), "utf8");
+		if (!parsesAsConfig(text)) return null;
+		try {
+			await writeConfigFile(text);
+		} catch (e) {
+			console.warn("dsh-background-by-model: could not restore the config from its backup", e);
+		}
+		console.warn("dsh-background-by-model: \"theme-config.json\" was missing or unreadable; restored the last saved copy from \"theme-config.json.bak\"");
+		return {
+			text,
+			source: "backup"
+		};
+	} catch {
+		return null;
+	}
+}
 async function readConfig() {
 	await ensureDir();
+	const file = await readConfigFile();
 	let raw = {};
-	try {
-		raw = JSON.parse(await readFile(configPath(), "utf8"));
+	if (file !== null) try {
+		raw = JSON.parse(file.text);
 	} catch {
 		raw = {};
 	}
 	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 the last good
+* copy (or, when there is none, with defaults) — right for painting and WRONG as a
+* basis for deleting images, because a store whose config could not be read at all
+* would then have zero referenced slots and every file on disk would look like an
+* orphan. That is the one way this feature could destroy a wallpaper collection, so
+* the two cases are told apart here and the sweep refuses rather than guesses:
+*
+*   - a live file that parses to an object → trusted (its rules are what they say);
+*   - no live file, and no backup either → trusted. A fresh store has images only
+*     if something wrote them, and nothing did;
+*   - a live file that is there but does not parse, or is not an object → the
+*     BACKUP is the answer, and only because it is exactly the config `readConfig`
+*     would restore: pruning against it is pruning against the rules the user is
+*     about to get back. When there is no parseable backup, this is `untrusted` and
+*     the sweep refuses.
+*
+* 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 live = null;
+	try {
+		live = await readFile(configPath(), "utf8");
+	} catch {
+		live = null;
+	}
+	if (live !== null && parsesAsConfig(live)) return {
+		config: normalizeConfig(await migrateLegacy(JSON.parse(live))),
+		trusted: true
+	};
+	let backup = null;
+	try {
+		backup = await readFile(configBackupPath(), "utf8");
+	} catch {
+		backup = null;
+	}
+	if (backup !== null && parsesAsConfig(backup)) return {
+		config: normalizeConfig(JSON.parse(backup)),
+		trusted: true
+	};
+	if (live === null && backup === null) return {
+		config: normalizeConfig({}),
+		trusted: true
+	};
+	return {
+		config: normalizeConfig({}),
+		trusted: false
+	};
+}
 const LEGACY_CONFIG_KEYS = /* @__PURE__ */ new Set([
 	"color",
 	"bgMode",
@@ -685,7 +948,10 @@ const LEGACY_CONFIG_KEYS = /* @__PURE__ */ new Set([
 const LEGACY_RULE_KEYS = /* @__PURE__ */ new Set([
 	"slot",
 	"bgState",
-	"bgMode"
+	"bgMode",
+	"wallpaperOpacity",
+	"brightness",
+	"blur"
 ]);
 const LEGACY_NESTED_KEYS = /* @__PURE__ */ new Set(["rules[].rotate.fadeMs"]);
 const warnedConfigKeys = /* @__PURE__ */ new Set();
@@ -739,11 +1005,10 @@ function warnUnknownConfigKeys(raw, normalized) {
 	}
 }
 async function writeConfig(config) {
-	await ensureDir();
 	try {
 		const normalized = normalizeConfig(config);
 		warnUnknownConfigKeys(config, normalized);
-		await writeFile(configPath(), JSON.stringify(normalized, null, 2), "utf8");
+		await writeConfigFile(serializeConfig(normalized));
 		return true;
 	} catch (e) {
 		console.error(`dsh-background-by-model: failed to write "${CONFIG_FILE}"`, e);
@@ -972,14 +1237,14 @@ async function fetchPresetConfig() {
 		ok: false,
 		error: "not a profile"
 	};
-	if (declared > 9) {
-		console.warn(`dsh-background-by-model: the recommended profile declares schema ${declared}, this build writes 9`);
+	if (declared > 10) {
+		console.warn(`dsh-background-by-model: the recommended profile declares schema ${declared}, this build writes 10`);
 		return {
 			ok: false,
 			error: "newer version"
 		};
 	}
-	if (declared < 9) console.warn(`dsh-background-by-model: the recommended profile is written for schema ${declared}; importing it with defaults for the fields it predates`);
+	if (declared < 10) console.warn(`dsh-background-by-model: the recommended profile is written for schema ${declared}; importing it with defaults for the fields it predates`);
 	const configRaw = await fetchPresetFile(PRESET_CONFIG, PRESET_CONFIG_MAX);
 	if (configRaw === null) return {
 		ok: false,
@@ -1126,7 +1391,7 @@ async function listSlots() {
 	}
 }
 /**
-* Empty the store: the config and every rule image, and nothing else.
+* Empty the store: the config, its backup and every rule image, and nothing else.
 *
 * The hard reset behind "use the recommended profile", and it has to be a real one
 * rather than a config overwrite: `nextSlot` hands out `m1`, `m2`, … as a running
@@ -1134,6 +1399,10 @@ async function listSlots() {
 * as a matter of course. Emptying first is what makes the profile's own slots free
 * to write, which is why no slot remapping is needed.
 *
+* The backup goes WITH the live file: a `.bak` left behind would be restored by the
+* next read, which would quietly undo the very replacement this call exists to
+* perform (`applyThemeFile`'s `wipeFirst`).
+*
 * `holiday-cache/` is deliberately untouched: downloaded art that belongs to no
 * slot and costs a round trip to get back. Pruning generations is
 * `pruneHolidayCache`'s job.
@@ -1144,8 +1413,8 @@ async function listSlots() {
 */
 async function resetStore() {
 	let ok = true;
-	try {
-		await rm(configPath(), { force: true });
+	for (const path of [configPath(), configBackupPath()]) try {
+		await rm(path, { force: true });
 	} catch (e) {
 		ok = false;
 		console.warn(`dsh-background-by-model: failed to remove "${CONFIG_FILE}"`, e);
@@ -1159,6 +1428,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 +1646,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 {
@@ -1284,7 +1655,7 @@ async function handleRpcMethod(ctx, endpoint, payload) {
 				value: {
 					config: await readConfig(),
 					slots: await listSlots(),
-					schema: 9
+					schema: 10
 				}
 			};
 			case "writeConfig": return {
@@ -1350,6 +1721,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)