dsh-background-by-model 0.5.5 → 0.7.1

package/lib/index.js

@@ -1,6 +1,50 @@
 import { access, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+//#region src/holiday.ts
+const HOLIDAYS = [{
+	id: "mid-autumn",
+	slot: "h-midautumn",
+	asset: "mid-autumn.webp",
+	color: "#384A77",
+	kind: "lunar"
+}, {
+	id: "national-day",
+	slot: "h-nationalday",
+	asset: "national-day.webp",
+	color: "#FFF6EB",
+	kind: "gregorian"
+}];
+//#endregion
 //#region src/schema.ts
+/**
+* The persisted configuration shape — declared exactly ONCE, for both halves.
+*
+* This shape used to be written out twice: the node half owns persistence and
+* sanitizes every write, the browser half owns the UI and its own reading of the
+* same file. A field added to only one side was silently dropped by the other
+* side's sanitizer — the matching slider stayed live in memory, `writeConfig`
+* wrote a config without it, and the next load fell back to the default.
+* `blurs.rightbar` / `rightbarOpacity` in 0.3.2 was exactly that bug, and the key
+* lists were duplicated 6 times across the two halves, so it was due to happen.
+*
+* The types, the key lists, the defaults and the pure normalizers therefore live
+* here and both halves import them: adding a field means editing this file, and
+* the two halves cannot disagree about the shape. The host additionally logs one
+* warning per unknown key while sanitizing a write (see `warnUnknownConfigKeys`
+* in `src/index.ts`), so a field that reaches the node half without being
+* declared here shows up in the host log instead of quietly disappearing.
+*
+* Nothing in this module may touch the DOM, Node or the Cordis context: it is
+* imported by the browser bundle and by the node half alike.
+*/
+const DEFAULT_BG_STATE = {
+	zoom: 1,
+	x: 0,
+	y: 0,
+	iw: 0,
+	ih: 0
+};
 /** Every accepted `bgMode`, in UI order. */
 const BG_MODES = [
 	"fit",
@@ -9,6 +53,26 @@ const BG_MODES = [
 	"tile",
 	"center"
 ];
+/** Every accepted `rotate.order`, in UI order. */
+const ROTATE_ORDERS = ["order", "shuffle"];
+/** Fastest allowed dwell time — below this the cross-fade never settles. */
+const ROTATE_MIN_MS = 5e3;
+/** Slowest allowed dwell time (24 h): one image per day is still "rotation". */
+const ROTATE_MAX_MS = 864e5;
+/** Longest allowed cross-fade; 0 is a hard cut. */
+const ROTATE_FADE_MAX_MS = 3e3;
+/** Everything off: the shipped default, and what a config predating this feature gets. */
+const DEFAULT_ROTATION = {
+	enabled: false,
+	intervalMs: 6e4,
+	order: "order",
+	advanceOnSwitch: false,
+	fadeMs: 320
+};
+/** A fresh rotation block (never hand out the shared default object). */
+function defaultRotation() {
+	return { ...DEFAULT_ROTATION };
+}
 /**
 * Main interface opacities (0..1), global (Interface page):
 *   `bg`      main background (`--dsw-alias-bg-base`)
@@ -60,6 +124,68 @@ const DEFAULT_PART_BLURS = {
 	rightbar: 0,
 	input: 0
 };
+/**
+* `#RRGGBB` → the `[h, s, l]` triple every rule stores (`s` and `l` in 0..1), or
+* null when the string is not a hex color.
+*
+* A holiday names its color as hex because that is how a color is quoted, and a
+* hand-converted triple is a magic number nothing downstream can check. The
+* conversion lives here rather than in ./holiday because `[h, s, l]` is this
+* module's own rule shape.
+*/
+function hexToHsl(hex) {
+	const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+	if (m === null) return null;
+	const n = parseInt(m[1], 16);
+	const r = (n >> 16 & 255) / 255;
+	const g = (n >> 8 & 255) / 255;
+	const b = (n & 255) / 255;
+	const max = Math.max(r, g, b);
+	const min = Math.min(r, g, b);
+	const l = (max + min) / 2;
+	const d = max - min;
+	if (d === 0) return [
+		0,
+		0,
+		l
+	];
+	const s = d / (1 - Math.abs(2 * l - 1));
+	let h;
+	if (max === r) h = 60 * ((g - b) / d % 6);
+	else if (max === g) h = 60 * ((b - r) / d + 2);
+	else h = 60 * ((r - g) / d + 4);
+	if (h < 0) h += 360;
+	return [
+		clamp(h, 0, 360, 0),
+		clamp01(s, 0),
+		clamp01(l, .5)
+	];
+}
+/**
+* One holiday's appearance, untouched.
+*
+* Holidays default to `fill` rather than a rule's `fit`: these are full-bleed
+* festival wallpapers, and `fit` would letterbox them on every aspect ratio the
+* art was not cut for.
+*/
+function defaultHolidayRule(def) {
+	const color = hexToHsl(def.color);
+	return {
+		id: def.id,
+		images: [{
+			slot: def.slot,
+			bgState: { ...DEFAULT_BG_STATE },
+			color
+		}],
+		match: "",
+		enabled: true,
+		color,
+		bgMode: "fill",
+		wallpaperOpacity: 1,
+		blur: 0,
+		rotate: defaultRotation()
+	};
+}
 /** Slot names reach the filesystem, so they are strictly whitelisted. */
 const SLOT_RE = /^[A-Za-z0-9_-]{1,32}$/;
 function clamp(n, lo, hi, def) {
@@ -86,23 +212,143 @@ function normalizeHsl(raw) {
 		clamp(raw[2], 0, 1, .25)
 	];
 }
-/** Coerce one persisted rule, or null when it lacks a usable id/slot. */
+/** Coerce one persisted rotation block; a config without one gets the shipped default. */
+function normalizeRotation(raw) {
+	const r = raw ?? {};
+	const d = DEFAULT_ROTATION;
+	return {
+		enabled: r.enabled === true,
+		intervalMs: clamp(r.intervalMs, ROTATE_MIN_MS, ROTATE_MAX_MS, d.intervalMs),
+		order: ROTATE_ORDERS.includes(r.order) ? r.order : d.order,
+		advanceOnSwitch: r.advanceOnSwitch === true,
+		fadeMs: clamp(r.fadeMs, 0, ROTATE_FADE_MAX_MS, d.fadeMs)
+	};
+}
+/** Own-property test for values that may be anything at all (a raw JSON entry). */
+function hasOwn(o, key) {
+	return Object.prototype.hasOwnProperty.call(o, key);
+}
+/**
+* Coerce one persisted image entry, or null when it lacks a usable slot.
+*
+* `inherit` is the RULE's own color, and it is applied only to an entry that has
+* no `color` key at all — the shape every release before 0.7.1 wrote, where a
+* rule's color was the only color there was. Lifting it here, once, is what makes
+* an upgrade a no-op on screen: a themed wallpaper keeps its theme instead of
+* silently dropping to the system palette, and it happens in the shared sanitizer
+* so both halves lift identically.
+*
+* The KEY's presence is the whole distinction, which is why `null` is not the
+* same as absent: an entry with `color: null` is an image the user explicitly set
+* to "follow the system theme", and re-inheriting the rule's color over that
+* would undo a deliberate choice on every load.
+*/
+function normalizeImage(raw, inherit = null) {
+	const i = raw ?? {};
+	if (typeof i.slot !== "string" || !SLOT_RE.test(i.slot)) return null;
+	return {
+		slot: i.slot,
+		bgState: normalizeBgState(i.bgState),
+		color: hasOwn(i, "color") ? normalizeHsl(i.color) : inherit
+	};
+}
+/**
+* Coerce one persisted rule, or null when it names no image AT ALL.
+*
+* Accepts BOTH image shapes: the 0.7 list (`images`), and the single
+* `slot`/`bgState` pair every earlier version wrote — the latter is lifted to a
+* one-entry list here rather than at a dozen call sites, which is what keeps the
+* rest of the codebase free of "old config" branches. Duplicate slots inside one
+* rule are dropped: two entries pointing at the same bytes would only make the
+* rotation look stuck.
+*
+* The rule's color is resolved FIRST and handed to every image entry, because it
+* is what an entry written before 0.7.1 inherits (`normalizeImage`). The rule keeps
+* it as well: it is not a default for its images at paint time any more, but it
+* is still what the rule paints once its last picture is gone.
+*
+* An EMPTY list is a legitimate rule, not a broken one: removing a rule's last
+* picture has to be expressible, and forcing an entry back in is what produced a
+* phantom blank image that took slot 1 and could never be deleted again (the next
+* upload landed at position 2 and the rule kept painting nothing). What such a
+* rule then does is `ruleCanPaint`'s business: with a color of its own it paints
+* the interface, with neither it is skipped by matching — which the card's own
+* hint says in so many words. Only a rule that names no image anywhere — no list,
+* no legacy slot, or a slot that could never be a filename — is dropped.
+*/
 function normalizeRule(raw) {
 	const r = raw ?? {};
 	const id = typeof r.id === "string" && r.id !== "" ? r.id : null;
-	const slot = typeof r.slot === "string" && SLOT_RE.test(r.slot) ? r.slot : null;
-	if (id === null || slot === null) return null;
+	if (id === null) return null;
+	const color = normalizeHsl(r.color);
+	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);
+		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,
+		bgState: normalizeBgState(r.bgState),
+		color
+	});
+	if (images.length === 0 && !hadList) return null;
 	const mode = BG_MODES.includes(r.bgMode) ? r.bgMode : "fit";
 	return {
 		id,
-		slot,
+		images,
 		match: typeof r.match === "string" ? r.match : "",
 		enabled: r.enabled !== false,
-		color: normalizeHsl(r.color),
+		color,
 		bgMode: mode,
 		wallpaperOpacity: clamp01(r.wallpaperOpacity, 1),
 		blur: clamp(r.blur, 0, 60, 0),
-		bgState: normalizeBgState(r.bgState)
+		rotate: normalizeRotation(r.rotate)
+	};
+}
+/**
+* Coerce one persisted holiday entry.
+*
+* `id`, `images` and every theme color (the rule's and each image's) come from
+* the DEFINITION, never from disk: a holiday's slot is the only thing tying it to
+* its bytes, and its theme color is a fixed part of what that holiday looks like —
+* so a stale or hand-edited value would either orphan the wallpaper, point the
+* holiday at a rule's image, or paint a festival in a color it does not have.
+* Everything else is sanitized exactly like a rule's field — except the image
+* list and the rotation, which stay the definition's own single image and stay
+* off, so a festival can never be swapped or cycled.
+*/
+function normalizeHolidayRule(def, raw) {
+	const r = raw ?? {};
+	const base = defaultHolidayRule(def);
+	return {
+		...base,
+		enabled: r.enabled !== false,
+		bgMode: BG_MODES.includes(r.bgMode) ? r.bgMode : base.bgMode,
+		wallpaperOpacity: clamp01(r.wallpaperOpacity, base.wallpaperOpacity),
+		blur: clamp(r.blur, 0, 60, base.blur),
+		images: base.images.map((image) => ({
+			slot: image.slot,
+			bgState: normalizeBgState(r.images?.[0]?.bgState ?? r.bgState),
+			color: image.color
+		}))
+	};
+}
+/** Coerce the whole holiday block; unknown ids are dropped, missing ones defaulted. */
+function normalizeHolidays(raw) {
+	const r = raw ?? {};
+	const stored = /* @__PURE__ */ new Map();
+	if (Array.isArray(r.items)) for (const item of r.items) {
+		const id = item?.id;
+		if (typeof id === "string") stored.set(id, item);
+	}
+	return {
+		enabled: r.enabled !== false,
+		items: HOLIDAYS.map((def) => normalizeHolidayRule(def, stored.get(def.id)))
 	};
 }
 /** Coerce an unknown persisted value into a valid ThemeConfig, falling back per-field. */
@@ -123,7 +369,8 @@ function normalizeConfig(raw) {
 		chatTextOpacity: clamp01(r.chatTextOpacity, 0),
 		trajectoryOpacity: clamp01(r.trajectoryOpacity, 1),
 		rightbarOpacity: typeof r.rightbarOpacity === "number" && isFinite(r.rightbarOpacity) ? clamp01(r.rightbarOpacity, 1) : null,
-		autoExtract: r.autoExtract !== false
+		autoExtract: r.autoExtract !== false,
+		holidays: normalizeHolidays(r.holidays)
 	};
 }
 //#endregion
@@ -201,14 +448,16 @@ async function migrateLegacy(raw) {
 	const next = {
 		rules: [{
 			id: "m1",
-			slot: "m1",
+			images: [{
+				slot: "m1",
+				bgState: r.bgState ?? {}
+			}],
 			match: "",
 			enabled: true,
 			color: Array.isArray(r.color) ? r.color : null,
 			bgMode: typeof r.bgMode === "string" ? r.bgMode : "fit",
 			wallpaperOpacity: typeof r.wallpaperOpacity === "number" ? r.wallpaperOpacity : 1,
-			blur: typeof r.blur === "number" ? r.blur : 0,
-			bgState: r.bgState ?? {}
+			blur: typeof r.blur === "number" ? r.blur : 0
 		}],
 		opacities: r.opacities,
 		blurs: r.blurs,
@@ -248,6 +497,7 @@ const LEGACY_CONFIG_KEYS = /* @__PURE__ */ new Set([
 	"blur",
 	"bgState"
 ]);
+const LEGACY_RULE_KEYS = /* @__PURE__ */ new Set(["slot", "bgState"]);
 const warnedConfigKeys = /* @__PURE__ */ new Set();
 function warnUnknownConfigKeys(raw, normalized) {
 	if (raw === null || typeof raw !== "object") return;
@@ -269,8 +519,23 @@ function warnUnknownConfigKeys(raw, normalized) {
 	const sent = Array.isArray(r.rules) ? r.rules[0] : void 0;
 	const have = normalized.rules[0];
 	if (sent !== null && typeof sent === "object" && have !== void 0) {
+		const rule = sent;
 		const keys = new Set(Object.keys(have));
-		for (const key of Object.keys(sent)) if (!keys.has(key)) warned(`rules[].${key}`);
+		for (const key of Object.keys(rule)) if (!keys.has(key) && !LEGACY_RULE_KEYS.has(key)) warned(`rules[].${key}`);
+		const nested = [[
+			"rules[].rotate",
+			rule.rotate,
+			have.rotate
+		], [
+			"rules[].images[]",
+			Array.isArray(rule.images) ? rule.images[0] : void 0,
+			have.images[0]
+		]];
+		for (const [label, got, known] of nested) {
+			if (got === null || typeof got !== "object" || known === null || known === void 0) continue;
+			const knownKeys = new Set(Object.keys(known));
+			for (const key of Object.keys(got)) if (!knownKeys.has(key)) warned(`${label}.${key}`);
+		}
 	}
 }
 async function writeConfig(config) {
@@ -294,17 +559,52 @@ function sniffImageMime(buf) {
 	if (buf.length >= 2 && buf[0] === 66 && buf[1] === 77) return "image/bmp";
 	return "image/jpeg";
 }
-/** Read one rule image as a data URL, or null when the slot is empty. */
+/**
+* Read one slot as a data URL, or null when it has nothing to serve.
+*
+* A holiday slot is answered from the package and from nowhere else — the data
+* directory is never consulted for it, which is what makes the festival art
+* impossible to swap. Everything else is the user's own bytes. Both are resolved
+* lazily, so nothing about the bundled art is loaded — or even looked for — until
+* a holiday actually reaches for it.
+*/
 async function readImage(slot) {
+	const asset = bundledAssetFor(slot);
+	if (asset !== null) {
+		const bundled = await readFileOrNull(bundledAssetPath(asset));
+		return bundled === null ? null : toDataUrl(bundled);
+	}
+	const own = await readFileOrNull(imagePath(slot));
+	return own === null ? null : toDataUrl(own);
+}
+async function readFileOrNull(path) {
 	try {
-		const buf = await readFile(imagePath(slot));
-		return `data:${sniffImageMime(buf)};base64,${buf.toString("base64")}`;
+		return await readFile(path);
 	} catch {
 		return null;
 	}
 }
+function toDataUrl(buf) {
+	return `data:${sniffImageMime(buf)};base64,${buf.toString("base64")}`;
+}
+/** Absolute path of one wallpaper bundled inside the package. */
+function bundledAssetPath(asset) {
+	return fileURLToPath(new URL(`../holiday/${asset}`, import.meta.url));
+}
+/**
+* The wallpaper bundled for one slot, or null when the slot is not a holiday's.
+*
+* This mapping is the ONLY thing that makes a holiday slot read-only and
+* package-served, so both `readImage` and `writeImage` go through it rather than
+* each testing the holiday list on their own. It reads no config: the bundled art
+* has stopped being a fallback that a flag could disable.
+*/
+function bundledAssetFor(slot) {
+	return HOLIDAYS.find((h) => h.slot === slot)?.asset ?? null;
+}
 /** Persist one rule image (null removes it); false keeps the previous file. */
 async function writeImage(slot, dataUrl) {
+	if (bundledAssetFor(slot) !== null) return false;
 	await ensureDir();
 	try {
 		if (dataUrl === null) {
@@ -333,6 +633,10 @@ async function listSlots() {
 * Returns { ok, dataUrl?, error? }; never throws.
 */
 async function fetchImageUrl(slot, url) {
+	if (bundledAssetFor(slot) !== null) return {
+		ok: false,
+		error: "read-only slot"
+	};
 	if (url === null) {
 		const ok = await writeImage(slot, null);
 		return {
@@ -435,7 +739,8 @@ async function handleRpcMethod(ctx, endpoint, payload) {
 				ok: true,
 				value: {
 					config: await readConfig(),
-					slots: await listSlots()
+					slots: await listSlots(),
+					schema: 4
 				}
 			};
 			case "writeConfig": return {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-background-by-model",
-  "version": "0.5.5",
-  "description": "Appearance plugin for DeepSeek Harness: an ordered list of model rules, each carrying its own wallpaper, theme color, layout mode, opacity and blur — the background follows the model you switch to.",
+  "version": "0.7.1",
+  "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 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",
     "dsh",
@@ -49,13 +49,19 @@
     "CHANGELOG.md",
     "CHANGELOG.zh.md",
     "cordis.patch.yml",
-    "example_img"
+    "example_img",
+    "holiday"
   ],
   "scripts": {
     "bundle": "tsdown",
     "watch": "tsdown --watch",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "tsdown && tsc -p tsconfig.json"
+    "check:holiday": "node scripts/holiday-check.ts",
+    "check:rotation": "node scripts/rotation-check.ts",
+    "check:repaint": "node scripts/repaint-check.ts",
+    "check:ui": "node scripts/ui-strings-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/repaint-check.ts && node scripts/ui-strings-check.ts && node scripts/node-half-check.mjs"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",