dsh-any-background 0.3.9 → 0.4.1

package/lib/index.js

@@ -1,4 +1,5 @@
-import { access, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { access, copyFile, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream } from "node:fs";
 import { Readable } from "node:stream";
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
@@ -50,6 +51,10 @@ const SUPPORTED_RELEASES = [
 	{
 		channel: "0.2.1",
 		release: "0.2.1-rc.2"
+	},
+	{
+		channel: "0.2.1",
+		release: "0.2.1-rc.3"
 	}
 ];
 const UNKNOWN_HOST_INFO = {
@@ -245,6 +250,42 @@ async function resolveHostInfo(installAnchor) {
 	return cache;
 }
 //#endregion
+//#region src/shared/rotation.ts
+/** ISO week key (Monday-first). */
+function isoWeekKey(d) {
+	const t = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+	const day = t.getUTCDay() || 7;
+	t.setUTCDate(t.getUTCDate() + 4 - day);
+	const yearStart = new Date(Date.UTC(t.getUTCFullYear(), 0, 1));
+	const week = Math.ceil(((t.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
+	return `${t.getUTCFullYear()}-W${week}`;
+}
+/** Whether the pool should advance right now. */
+function rotationDue(rot, now = /* @__PURE__ */ new Date()) {
+	if (!rot.enabled || rot.items.length === 0) return false;
+	if (rot.interval === "reload") return true;
+	const last = rot.lastRotate !== null ? new Date(rot.lastRotate) : null;
+	if (last === null || isNaN(last.getTime())) return true;
+	if (rot.interval === "hourly") return hourKey(last) !== hourKey(now);
+	if (rot.interval === "daily") return last.toDateString() !== now.toDateString();
+	return isoWeekKey(last) !== isoWeekKey(now);
+}
+/** Epoch-hour bucket: hourly cadence advances on each full hour boundary
+*  (in whole-hour timezones — UTC+8 among them — that is exactly the local
+*  on-the-hour tick). */
+const hourKey = (d) => Math.floor(d.getTime() / 36e5);
+/** Pick the next pool index under the configured mode. */
+function pickNextRotationIndex(rot) {
+	const n = rot.items.length;
+	if (n === 0) return -1;
+	if (rot.mode === "shuffle" && n > 1) {
+		let idx = rot.current;
+		while (idx === rot.current) idx = Math.floor(Math.random() * n);
+		return idx;
+	}
+	return (rot.current + 1) % n;
+}
+//#endregion
 //#region src/index.ts
 /**
 * Node half of dsh-any-background: file-backed theme persistence.
@@ -272,9 +313,12 @@ const WALLPAPER_ROUTE = "/dsh-any-background/wallpaper";
 const WALLPAPER_UPLOAD_ROUTE = "/dsh-any-background/wallpaper/upload";
 const FONT_ROUTE = "/dsh-any-background/font";
 const FONT_UPLOAD_ROUTE = "/dsh-any-background/font/upload";
+/** Serves one rotation-pool image by name (the export path fetches these). */
+const ROTATION_FILE_ROUTE = "/dsh-any-background/rotation/file";
 const UPLOAD_TMP = "wallpaper.upload.tmp";
 const VIDEO_UPLOAD_TMP = "video.upload.tmp";
 const FONT_UPLOAD_TMP = "font.upload.tmp";
+const VIDEO_DOWNLOAD_TMP = "video.download.tmp";
 const WALLPAPER_UPLOAD_MAX = 104857600;
 const VIDEO_UPLOAD_MAX = 2147483648;
 const FONT_UPLOAD_MAX = 104857600;
@@ -301,6 +345,20 @@ const VIDEO_CANDIDATES = [
 	"wallpaper.mkv",
 	"wallpaper.video"
 ];
+/** Reverse of videoFileName for the stray-adoption path below: a config that
+*  lost videoMime would otherwise serve the stored file as
+*  application/octet-stream, which no <video> element plays. The legacy
+*  extensionless name keeps null — its container is unknowable from the name. */
+function mimeForVideoFile(name) {
+	switch (name) {
+		case "wallpaper.mp4": return "video/mp4";
+		case "wallpaper.webm": return "video/webm";
+		case "wallpaper.ogv": return "video/ogg";
+		case "wallpaper.mov": return "video/quicktime";
+		case "wallpaper.mkv": return "video/x-matroska";
+		default: return null;
+	}
+}
 /** Font slot: one font owns the slot, named by format like the video slot. */
 function fontFileName(mime) {
 	switch (mime) {
@@ -468,6 +526,21 @@ const exists = async (p) => {
 		return false;
 	}
 };
+/** Read a file's first bytes for magic-number sniffing (null when unreadable). */
+const readHead = async (p, n) => {
+	try {
+		const head = Buffer.alloc(n);
+		const fh = await open(p, "r");
+		try {
+			const { bytesRead } = await fh.read(head, 0, n, 0);
+			return bytesRead === 0 ? null : head.subarray(0, bytesRead);
+		} finally {
+			await fh.close();
+		}
+	} catch {
+		return null;
+	}
+};
 /** Locate the stored video: the recorded MIME decides the expected name; a
 *  legacy extensionless wallpaper.video is renamed on first access. */
 async function findVideoFile() {
@@ -489,6 +562,20 @@ async function findVideoFile() {
 		} catch {
 			return null;
 		}
+		if (cfg.videoMime === null) {
+			const mime = mimeForVideoFile(name);
+			if (mime !== null) {
+				const fresh = await readConfig();
+				if (fresh.videoMime !== mime) {
+					fresh.videoMime = mime;
+					await writeConfig(fresh);
+				}
+				return {
+					path: p,
+					mime
+				};
+			}
+		}
 		return {
 			path: p,
 			mime: cfg.videoMime
@@ -499,40 +586,50 @@ async function findVideoFile() {
 function clamp(n, lo, hi, def) {
 	return typeof n === "number" && isFinite(n) ? Math.min(hi, Math.max(lo, n)) : def;
 }
-/** Locate the stored font: the recorded MIME decides the expected name; stray
-*  files from a lost config write are adopted via rename (mirrors the video
-*  slot's recovery). */
+/** Locate the stored font: the recorded MIME decides the expected name. A
+*  stray from a lost config write (or one whose recorded MIME no longer
+*  matches the bytes on disk) is adopted by sniffing the file's REAL container
+*  magic — never by trusting its name: the old name-based rename moved woff2
+*  bytes into font.ttf, and the next lookup then served them as font/ttf. The
+*  sniffed answer is renamed into place and persisted, so later lookups
+*  resolve by name (mirrors the video slot's recovery). */
 async function findFontFile() {
-	const mime = (await readConfig()).fontMime ?? "font/ttf";
-	const expected = fontPathFor(mime);
-	if (await exists(expected)) return {
-		path: expected,
-		mime
-	};
+	const cfg = await readConfig();
+	if (cfg.fontMime !== null) {
+		const expected = fontPathFor(cfg.fontMime);
+		if (await exists(expected)) return {
+			path: expected,
+			mime: cfg.fontMime
+		};
+	}
 	for (const name of FONT_CANDIDATES) {
 		const p = dshHomePath(DATA_DIR, name);
 		if (!await exists(p)) continue;
-		const foundMime = mimeForFontFile(name);
+		const head = await readHead(p, 4);
+		if (head === null) continue;
+		const sniffed = sniffFontMime(head);
+		if (sniffed === null) continue;
+		const target = fontPathFor(sniffed);
 		try {
-			await rename(p, expected);
-			return {
-				path: expected,
-				mime: foundMime
-			};
+			if (target !== p) {
+				await rm(target, { force: true });
+				await rename(p, target);
+			}
 		} catch {
 			return null;
 		}
+		const fresh = await readConfig();
+		if (fresh.fontMime !== sniffed) {
+			fresh.fontMime = sniffed;
+			await writeConfig(fresh);
+		}
+		return {
+			path: target,
+			mime: sniffed
+		};
 	}
 	return null;
 }
-function mimeForFontFile(name) {
-	switch (name) {
-		case "font.woff2": return "font/woff2";
-		case "font.woff": return "font/woff";
-		case "font.otf": return "font/otf";
-		default: return "font/ttf";
-	}
-}
 async function fontUrl() {
 	return await findFontFile() ? FONT_ROUTE : null;
 }
@@ -781,7 +878,7 @@ function normalizeRotation(raw) {
 	return {
 		enabled: r.enabled === true,
 		mode: r.mode === "order" ? "order" : "shuffle",
-		interval: r.interval === "reload" || r.interval === "weekly" ? r.interval : "daily",
+		interval: r.interval === "reload" || r.interval === "hourly" || r.interval === "weekly" ? r.interval : "daily",
 		current: typeof r.current === "number" && isFinite(r.current) && r.current >= 0 ? Math.floor(r.current) : 0,
 		items,
 		lastRotate: typeof r.lastRotate === "string" ? r.lastRotate : null
@@ -798,9 +895,12 @@ function normalizeSchedule(raw) {
 		nightStart: typeof r.nightStart === "string" && HHMM_RE.test(r.nightStart) ? r.nightStart : DEFAULT_CONFIG.schedule.nightStart
 	};
 }
+let dirEnsured = false;
 async function ensureDir() {
+	if (dirEnsured) return;
 	try {
 		await mkdir(dataDir(), { recursive: true });
+		dirEnsured = true;
 	} catch (e) {
 		console.warn(`dsh-any-background: cannot create data dir "${dataDir()}"`, e);
 	}
@@ -826,7 +926,7 @@ async function readConfig() {
 		text = await readFile(file, "utf8");
 	} catch {
 		dropConfigCache();
-		return { ...DEFAULT_CONFIG };
+		return structuredClone(DEFAULT_CONFIG);
 	}
 	try {
 		const parsed = normalizeConfig(JSON.parse(text));
@@ -840,7 +940,7 @@ async function readConfig() {
 			console.warn(`dsh-any-background: theme-config.json was corrupt, archived to "${into}" and reset to defaults`, e);
 		} catch {}
 		dropConfigCache();
-		return { ...DEFAULT_CONFIG };
+		return structuredClone(DEFAULT_CONFIG);
 	}
 }
 const LEGACY_CONFIG_KEYS = /* @__PURE__ */ new Set(["opacity"]);
@@ -871,13 +971,13 @@ function warnUnknownConfigKeys(raw, normalized) {
 }
 async function writeConfig(config) {
 	await ensureDir();
+	dropConfigCache();
 	const tmp = `${configPath()}.tmp`;
 	try {
 		const normalized = normalizeConfig(config);
 		warnUnknownConfigKeys(config, normalized);
 		await writeFile(tmp, JSON.stringify(normalized, null, 2), "utf8");
 		await rename(tmp, configPath());
-		dropConfigCache();
 		return true;
 	} catch (e) {
 		console.error(`dsh-any-background: failed to write "${CONFIG_FILE}"`, e);
@@ -1061,7 +1161,7 @@ async function handleRotationAdd(payload) {
 		ok: false,
 		error: "too many items"
 	};
-	const file = `wp-${Date.now().toString(36)}.${imageExtFor(sniffImageMime(buf))}`;
+	const file = `wp-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}.${imageExtFor(sniffImageMime(buf))}`;
 	try {
 		await writeFile(dshHomePath(DATA_DIR, ROTATION_DIR, file), buf);
 	} catch (e) {
@@ -1128,27 +1228,99 @@ async function handleRotationSet(payload) {
 		ok: false,
 		error: "not found"
 	};
-	let buf;
 	try {
-		buf = await readFile(dshHomePath(DATA_DIR, ROTATION_DIR, item.file));
-	} catch {
+		await copyFile(dshHomePath(DATA_DIR, ROTATION_DIR, item.file), wallpaperPath());
+	} catch (e) {
+		console.error("dsh-any-background: failed to activate a rotation wallpaper", e);
 		return {
 			ok: false,
-			error: "file missing"
+			error: typeof e === "object" && e !== null && e.code === "ENOENT" ? "file missing" : "write failed"
 		};
 	}
 	try {
-		await writeFile(wallpaperPath(), buf);
-	} catch (e) {
-		console.error("dsh-any-background: failed to activate a rotation wallpaper", e);
+		const fresh = await readConfig();
+		if (fresh.rotation.items[i] !== void 0) {
+			if (!await writeConfig({
+				...fresh,
+				rotation: {
+					...fresh.rotation,
+					current: i,
+					lastRotate: fresh.rotation.lastRotate ?? (/* @__PURE__ */ new Date()).toISOString()
+				}
+			})) console.warn("dsh-any-background: rotation cursor did not persist (the client save will catch up)");
+		}
+	} catch {}
+	return {
+		ok: true,
+		wallpaperUrl: WALLPAPER_ROUTE
+	};
+}
+/** Replace the whole rotation pool from an imported theme (v3 export): each
+*  entry's bytes are written under the name the exported config's metadata
+*  already points at, files the imported pool does not reference are dropped,
+*  and the config's item list is rebuilt. Wholesale replacement matches import
+*  semantics — the rotation state lands exactly as it left the source machine
+*  (a v2 export could not carry pool bytes, so its entries pointed at files
+*  that never travelled and every activation failed with 'file missing'). */
+async function handleRotationRestore(payload) {
+	const raw = payload?.items;
+	if (!Array.isArray(raw)) return {
+		ok: false,
+		error: "invalid payload"
+	};
+	const entries = [];
+	for (const it of raw.slice(0, MAX_ROTATION_ITEMS)) {
+		const e = it ?? {};
+		const file = safeRotationFile(e.file);
+		if (file === null) return {
+			ok: false,
+			error: "invalid file name"
+		};
+		if (entries.some((x) => x.file === file)) continue;
+		const buf = decodeImageDataUrl(e.dataUrl);
+		if (buf === null) return {
+			ok: false,
+			error: "invalid image"
+		};
+		entries.push({
+			file,
+			thumb: sanitizeThumb(e.thumb),
+			buf
+		});
+	}
+	await ensureDir();
+	await ensureRotationDir();
+	if (await exists(rotationDir())) {
+		for (const name of await readdir(rotationDir())) if (!entries.some((x) => x.file === name)) await rm(dshHomePath(DATA_DIR, ROTATION_DIR, name), { force: true });
+	}
+	try {
+		for (const e of entries) await writeFile(dshHomePath(DATA_DIR, ROTATION_DIR, e.file), e.buf);
+	} catch (err) {
+		console.error("dsh-any-background: failed to restore the rotation pool", err);
 		return {
 			ok: false,
 			error: "write failed"
 		};
 	}
+	const items = entries.map((e) => ({
+		file: e.file,
+		thumb: e.thumb
+	}));
+	const fresh = await readConfig();
+	if (!await writeConfig({
+		...fresh,
+		rotation: {
+			...fresh.rotation,
+			current: Math.min(fresh.rotation.current, Math.max(0, items.length - 1)),
+			items
+		}
+	})) return {
+		ok: false,
+		error: "config write failed"
+	};
 	return {
 		ok: true,
-		wallpaperUrl: WALLPAPER_ROUTE
+		items
 	};
 }
 async function videoUrl() {
@@ -1220,7 +1392,7 @@ async function writeVideoFromUrl(url) {
 		error: "too large"
 	};
 	await ensureDir();
-	const tmp = dshHomePath(DATA_DIR, "video.download.tmp");
+	const tmp = dshHomePath(DATA_DIR, VIDEO_DOWNLOAD_TMP);
 	const target = videoPathFor(mime);
 	try {
 		if (res.body === null) return {
@@ -1526,16 +1698,13 @@ async function serveWallpaper(req, res) {
 			res.end();
 			return;
 		}
-		const mime = sniffImageMime(await new Promise((resolve, reject) => {
-			const chunks = [];
-			const s = createReadStream(wallpaperPath(), {
-				start: 0,
-				end: 15
-			});
-			s.on("data", (c) => chunks.push(c));
-			s.on("end", () => resolve(Buffer.concat(chunks)));
-			s.on("error", reject);
-		}));
+		const head = await readHead(wallpaperPath(), 16);
+		if (head === null) {
+			res.writeHead(404);
+			res.end("no wallpaper stored");
+			return;
+		}
+		const mime = sniffImageMime(head);
 		res.writeHead(200, {
 			"Content-Type": mime,
 			"Content-Length": st.size,
@@ -1607,6 +1776,16 @@ async function handleWallpaperUpload(req, res) {
 					}));
 					return;
 				}
+				const head = await readHead(tmp, 12);
+				if (head === null || !isImageBytes(head)) {
+					await rm(tmp, { force: true });
+					res.writeHead(415, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({
+						ok: false,
+						error: "not an image"
+					}));
+					return;
+				}
 				await rm(wallpaperPath(), { force: true });
 				await rename(tmp, wallpaperPath());
 				res.writeHead(200, { "Content-Type": "application/json" });
@@ -1631,6 +1810,47 @@ async function handleWallpaperUpload(req, res) {
 		} catch {}
 	}
 }
+/** Serve one rotation-pool image by its `?f=<name>` query. The name goes
+*  through the same pattern fence the config sanitizer uses (bare file name
+*  with a known image extension), so there is no path traversal; unfenced like
+*  the other image serve routes (an <img> fetch carries no auth headers). */
+async function serveRotationFile(req, res) {
+	if (req.method !== "GET" && req.method !== "HEAD") {
+		res.writeHead(405);
+		res.end();
+		return;
+	}
+	let name = null;
+	try {
+		name = safeRotationFile(new URL(req.url ?? "/", "http://localhost").searchParams.get("f"));
+	} catch {
+		name = null;
+	}
+	if (name === null) {
+		res.writeHead(400);
+		res.end("invalid file name");
+		return;
+	}
+	try {
+		const p = dshHomePath(DATA_DIR, ROTATION_DIR, name);
+		const st = await stat(p);
+		const head = await readHead(p, 12);
+		if (head === null) throw new Error("unreadable");
+		res.writeHead(200, {
+			"Content-Type": sniffImageMime(head),
+			"Content-Length": st.size,
+			"Cache-Control": "no-store"
+		});
+		if (req.method === "HEAD") {
+			res.end();
+			return;
+		}
+		createReadStream(p).pipe(res);
+	} catch {
+		res.writeHead(404);
+		res.end("no such rotation image");
+	}
+}
 /** Stream the stored custom font: sniffed MIME, no caching (uploads replace
 *  the file in place). Fonts need no Range support — the browser fetches once. */
 async function serveFont(req, res) {
@@ -1790,36 +2010,22 @@ async function removeFontFile() {
 const NS = "dshAnyBackground";
 const RPC_CHANNEL = "/dsh-any-background";
 const RPC_BODY_MAX = 314572800;
-/** ISO week key — mirrors the client's rotationDue so daily/weekly cadence
-*  decisions agree across both halves. */
-function isoWeekKey(d) {
-	const t = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
-	const day = t.getUTCDay() || 7;
-	t.setUTCDate(t.getUTCDate() + 4 - day);
-	const yearStart = new Date(Date.UTC(t.getUTCFullYear(), 0, 1));
-	const week = Math.ceil(((t.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
-	return `${t.getUTCFullYear()}-W${week}`;
-}
 /** Advance the rotation pool when its cadence is due: pick the next item,
 *  copy it over the active wallpaper slot, and persist the rotation state.
 *  Runs inside `read` so a reload restores the NEW wallpaper directly — the
 *  old one never reaches the screen. The client's maybeRotate stays as a
-*  fallback and skips when this already advanced (the `rotated` flag). */
+*  fallback and skips when this already advanced (the `rotated` flag).
+*  The due/next math is the SHARED implementation (`src/shared/rotation.ts`)
+*  so both halves can never disagree on a day/week boundary. */
 async function advanceRotationIfDue() {
 	const rot = (await readConfig()).rotation;
-	if (!rot.enabled || rot.items.length === 0) return false;
+	if (!rotationDue(rot)) return false;
 	const now = /* @__PURE__ */ new Date();
-	const last = rot.lastRotate !== null ? new Date(rot.lastRotate) : null;
-	if (!(rot.interval === "reload" || last === null || isNaN(last.getTime()) || (rot.interval === "daily" ? last.toDateString() !== now.toDateString() : isoWeekKey(last) !== isoWeekKey(now)))) return false;
-	const n = rot.items.length;
-	let idx = rot.current;
-	if (rot.mode === "shuffle" && n > 1) while (idx === rot.current) idx = Math.floor(Math.random() * n);
-	else idx = (rot.current + 1) % n;
+	const idx = pickNextRotationIndex(rot);
 	const item = rot.items[idx];
 	if (item === void 0) return false;
 	try {
-		const buf = await readFile(dshHomePath(DATA_DIR, ROTATION_DIR, item.file));
-		await writeFile(wallpaperPath(), buf);
+		await copyFile(dshHomePath(DATA_DIR, ROTATION_DIR, item.file), wallpaperPath());
 	} catch (e) {
 		console.error("dsh-any-background: failed to advance the rotation pool", e);
 		return false;
@@ -1844,17 +2050,22 @@ async function handleRpcMethod(endpoint, payload, hostInfo) {
 				const rotated = await advanceRotationIfDue();
 				const config = await readConfig();
 				const firstRun = !await exists(configPath());
-				if (firstRun) await writeConfig(config);
+				const [wpServeUrl, vidServeUrl, fntServeUrl, host] = await Promise.all([
+					wallpaperServeUrl(),
+					videoUrl(),
+					fontUrl(),
+					hostInfo
+				]);
 				return {
 					ok: true,
 					value: {
 						config,
-						wallpaperUrl: await wallpaperServeUrl(),
-						videoUrl: await videoUrl(),
-						fontUrl: await fontUrl(),
+						wallpaperUrl: wpServeUrl,
+						videoUrl: vidServeUrl,
+						fontUrl: fntServeUrl,
 						rotated,
 						firstRun,
-						host: await hostInfo
+						host
 					}
 				};
 			}
@@ -1890,6 +2101,10 @@ async function handleRpcMethod(endpoint, payload, hostInfo) {
 				ok: true,
 				value: await handleRotationSet(payload)
 			};
+			case "rotationRestore": return {
+				ok: true,
+				value: await handleRotationRestore(payload)
+			};
 			case "removeFont": return {
 				ok: true,
 				value: await removeFontFile()
@@ -1914,7 +2129,43 @@ async function handleRpcMethod(endpoint, payload, hostInfo) {
 		};
 	}
 }
+const KEEP_CORRUPT_ARCHIVES = 3;
+const ORPHAN_GRACE_MS = 6e5;
+async function sweepDataDir() {
+	try {
+		const entries = await readdir(dataDir());
+		for (const name of entries) if (name === UPLOAD_TMP || name === VIDEO_UPLOAD_TMP || name === FONT_UPLOAD_TMP || name === VIDEO_DOWNLOAD_TMP) await rm(dshHomePath(DATA_DIR, name), { force: true });
+		const corrupts = [];
+		for (const name of entries) {
+			if (!/^theme-config\.json\.corrupt-\d+$/.test(name)) continue;
+			try {
+				const st = await stat(dshHomePath(DATA_DIR, name));
+				corrupts.push({
+					name,
+					mtime: st.mtimeMs
+				});
+			} catch {}
+		}
+		corrupts.sort((a, b) => b.mtime - a.mtime);
+		for (const c of corrupts.slice(KEEP_CORRUPT_ARCHIVES)) await rm(dshHomePath(DATA_DIR, c.name), { force: true });
+		if (await exists(rotationDir())) {
+			const referenced = new Set((await readConfig()).rotation.items.map((it) => it.file));
+			const now = Date.now();
+			for (const name of await readdir(rotationDir())) {
+				if (referenced.has(name)) continue;
+				const p = dshHomePath(DATA_DIR, ROTATION_DIR, name);
+				try {
+					if (now - (await stat(p)).mtimeMs < ORPHAN_GRACE_MS) continue;
+				} catch {
+					continue;
+				}
+				await rm(p, { force: true });
+			}
+		}
+	} catch {}
+}
 function apply(ctx) {
+	sweepDataDir();
 	const hostInfo = resolveHostInfo(ctx.profileContext?.installAnchor).catch((e) => {
 		console.warn("dsh-any-background: host release detection failed, falling back to DOM probing", e);
 		return UNKNOWN_HOST_INFO;
@@ -2059,6 +2310,11 @@ function apply(ctx) {
 			path: WALLPAPER_UPLOAD_ROUTE,
 			handler: fenceUpload(handleWallpaperUpload)
 		}), "dsh-any-background: wallpaper upload route");
+		webCtx.effect(() => webCtx.webServer.register({
+			kind: "prefix",
+			path: ROTATION_FILE_ROUTE,
+			handler: serveRotationFile
+		}), "dsh-any-background: rotation file route");
 		webCtx.effect(() => webCtx.webServer.register({
 			kind: "prefix",
 			path: FONT_ROUTE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-any-background",
-  "version": "0.3.9",
+  "version": "0.4.1",
   "description": "Appearance plugin for DeepSeek Harness: custom theme color (PS-style color wheel), background wallpaper with opacity/blur controls, and separate main/settings interface opacity.",
   "keywords": [
     "deepseek-harness",
@@ -23,7 +23,7 @@
   "author": "Tkingxiao",
   "type": "module",
   "engines": {
-    "dsh": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.0-rc.1"
+    "dsh": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || >=0.2.0-rc.1"
   },
   "exports": {
     ".": {
@@ -64,12 +64,12 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-store": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-client-ui-theme": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || >=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-store": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || >=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-connection": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || >=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || >=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || >=0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-theme": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || >=0.2.0-rc.1",
     "react": "^18.2.0",
     "dsh-better-sidebar": ">=0.4.0"
   },
@@ -104,7 +104,7 @@
   },
   "dsh": {
     "compatibility": {
-      "dsh": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || >=0.2.0-rc.1",
+      "dsh": "0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || >=0.2.0-rc.1",
       "dshReleases": {
         "0.2.0-rc.1": "compatible",
         "0.2.0-rc.2": "compatible",
@@ -114,7 +114,8 @@
         "0.2.1-alpha.4": "compatible",
         "0.2.1-alpha.5": "compatible",
         "0.2.1-rc.1": "compatible",
-        "0.2.1-rc.2": "compatible"
+        "0.2.1-rc.2": "compatible",
+        "0.2.1-rc.3": "compatible"
       }
     },
     "bundle": {