dsh-background-by-model 0.9.2 → 0.10.0

package/lib/index.js

@@ -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 ?? {};
@@ -508,8 +551,9 @@ function orphanSlots(stored, referenced, kept = []) {
 * `/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
 *
@@ -521,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 = [
@@ -622,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);
@@ -670,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,
@@ -686,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);
 	}
@@ -699,11 +760,121 @@ 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 = {};
 	}
@@ -712,21 +883,21 @@ async function readConfig() {
 /**
 * 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.
+* `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
@@ -737,31 +908,33 @@ async function readConfig() {
 */
 async function readConfigForSweep() {
 	await ensureDir();
-	let text;
+	let live = null;
 	try {
-		text = await readFile(configPath(), "utf8");
+		live = await readFile(configPath(), "utf8");
 	} catch {
-		return {
-			config: await readConfig(),
-			trusted: true
-		};
+		live = null;
 	}
-	let raw;
+	if (live !== null && parsesAsConfig(live)) return {
+		config: normalizeConfig(await migrateLegacy(JSON.parse(live))),
+		trusted: true
+	};
+	let backup = null;
 	try {
-		raw = JSON.parse(text);
+		backup = await readFile(configBackupPath(), "utf8");
 	} catch {
-		return {
-			config: normalizeConfig({}),
-			trusted: false
-		};
+		backup = null;
 	}
-	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {
+	if (backup !== null && parsesAsConfig(backup)) return {
+		config: normalizeConfig(JSON.parse(backup)),
+		trusted: true
+	};
+	if (live === null && backup === null) return {
 		config: normalizeConfig({}),
-		trusted: false
+		trusted: true
 	};
 	return {
-		config: normalizeConfig(await migrateLegacy(raw)),
-		trusted: true
+		config: normalizeConfig({}),
+		trusted: false
 	};
 }
 const LEGACY_CONFIG_KEYS = /* @__PURE__ */ new Set([
@@ -775,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();
@@ -829,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);
@@ -1062,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,
@@ -1216,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
@@ -1224,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.
@@ -1234,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);
@@ -1476,7 +1655,7 @@ async function handleRpcMethod(ctx, endpoint, payload) {
 				value: {
 					config: await readConfig(),
 					slots: await listSlots(),
-					schema: 9
+					schema: 10
 				}
 			};
 			case "writeConfig": return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-background-by-model",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "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",