dsh-background-by-model 0.2.4 → 0.3.0

package/lib/index.js

@@ -1,51 +1,42 @@
-import { access, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { createReadStream, createWriteStream } from "node:fs";
+import { access, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
 //#region src/index.ts
 /**
-* Node half of dsh-background-by-model: file-backed theme persistence.
+* Node half of dsh-background-by-model: file-backed rule persistence.
 *
 * Owns the `~/.dsh/.dsh-background-by-model-data/` store and exposes a small RPC
 * surface on the dedicated `/dsh-background-by-model` channel (never the shared
 * `/api`, so slash commands stay intact).
 *
-*   theme-config.json   settings
-*   wallpaper.jpg       background image
-*   wallpaper.<ext>     background video, named by MIME (mp4/webm/ogv/mov/mkv);
-*                       played over HTTP route /dsh-background-by-model/video and
-*                       uploaded to /dsh-background-by-model/video/upload as raw
-*                       bytes — never base64 through the RPC channel.
+*   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)
+*
+* Images travel as data URLs over the RPC channel — there is no separate HTTP
+* image route. A legacy single-wallpaper / video-background store is migrated
+* to rule 1 on first read.
 */
 const name = "dsh-background-by-model";
 const inject = ["connection", "webServer"];
 const DATA_DIR = ".dsh-background-by-model-data";
 const CONFIG_FILE = "theme-config.json";
-const WALLPAPER_FILE = "wallpaper.jpg";
-const VIDEO_ROUTE = "/dsh-background-by-model/video";
-const UPLOAD_ROUTE = "/dsh-background-by-model/video/upload";
-const UPLOAD_TMP = "wallpaper.upload.tmp";
-const WALLPAPER_FETCH_MAX = 26214400;
-const WALLPAPER_FETCH_TIMEOUT = 2e4;
-function videoFileName(mime) {
-	switch (mime) {
-		case "video/mp4": return "wallpaper.mp4";
-		case "video/webm": return "wallpaper.webm";
-		case "video/ogg": return "wallpaper.ogv";
-		case "video/quicktime": return "wallpaper.mov";
-		case "video/x-matroska": return "wallpaper.mkv";
-		default: return "wallpaper.video";
-	}
-}
-const VIDEO_CANDIDATES = [
+const IMAGE_PREFIX = "modelbg-";
+const LEGACY_WALLPAPER = "wallpaper.jpg";
+const LEGACY_FILES = [
 	"wallpaper.mp4",
 	"wallpaper.webm",
 	"wallpaper.ogv",
 	"wallpaper.mov",
 	"wallpaper.mkv",
-	"wallpaper.video"
+	"wallpaper.video",
+	"wallpaper.upload.tmp"
 ];
+/** Slot names reach the filesystem, so they are strictly whitelisted. */
+const SLOT_RE = /^[A-Za-z0-9_-]{1,32}$/;
+const WALLPAPER_FETCH_MAX = 26214400;
+const WALLPAPER_FETCH_TIMEOUT = 2e4;
 const DEFAULT_CONFIG = {
-	color: null,
+	rules: [],
 	opacities: {
 		bg: .85,
 		sidebar: .93,
@@ -62,34 +53,13 @@ const DEFAULT_CONFIG = {
 		input: 0
 	},
 	settingsOpacity: 1,
-	wallpaperOpacity: 1,
-	blur: 0,
-	bgState: {
-		zoom: 1,
-		x: 0,
-		y: 0,
-		iw: 0,
-		ih: 0
-	},
-	videoBgState: {
-		zoom: 1,
-		x: 0,
-		y: 0,
-		iw: 0,
-		ih: 0
-	},
-	backgroundType: "image",
-	bgMode: "fit",
-	videoMime: null,
-	generatedBg: null,
-	regenerateOnReload: false,
 	chatTextOpacity: 0,
 	trajectoryOpacity: 1
 };
 const dataDir = () => dshHomePath(DATA_DIR);
 const configPath = () => dshHomePath(DATA_DIR, CONFIG_FILE);
-const wallpaperPath = () => dshHomePath(DATA_DIR, WALLPAPER_FILE);
-const videoPathFor = (mime) => dshHomePath(DATA_DIR, videoFileName(mime));
+const legacyWallpaperPath = () => dshHomePath(DATA_DIR, LEGACY_WALLPAPER);
+const imagePath = (slot) => dshHomePath(DATA_DIR, `${IMAGE_PREFIX}${slot}`);
 const exists = async (p) => {
 	try {
 		await access(p);
@@ -98,72 +68,55 @@ const exists = async (p) => {
 		return false;
 	}
 };
-/** Locate the stored video: the recorded MIME decides the expected name; a
-*  legacy extensionless wallpaper.video is renamed on first access. */
-async function findVideoFile() {
-	const cfg = await readConfig();
-	const expected = videoPathFor(cfg.videoMime);
-	if (await exists(expected)) return {
-		path: expected,
-		mime: cfg.videoMime
-	};
-	for (const name of VIDEO_CANDIDATES) {
-		const p = dshHomePath(DATA_DIR, name);
-		if (!await exists(p)) continue;
-		if (cfg.videoMime !== null && name !== videoFileName(cfg.videoMime)) try {
-			await rename(p, expected);
-			return {
-				path: expected,
-				mime: cfg.videoMime
-			};
-		} catch {
-			return null;
-		}
-		return {
-			path: p,
-			mime: cfg.videoMime
-		};
-	}
-	return null;
-}
 function clamp(n, lo, hi, def) {
 	return typeof n === "number" && isFinite(n) ? Math.min(hi, Math.max(lo, n)) : def;
 }
+const clamp01 = (n, def) => clamp(n, 0, 1, def);
 function normalizeBgState(s) {
+	const v = s ?? {};
 	return {
-		zoom: clamp(s.zoom, .1, 10, 1),
-		x: typeof s.x === "number" && isFinite(s.x) ? s.x : 0,
-		y: typeof s.y === "number" && isFinite(s.y) ? s.y : 0,
-		iw: typeof s.iw === "number" && s.iw > 0 ? s.iw : 0,
-		ih: typeof s.ih === "number" && s.ih > 0 ? s.ih : 0
+		zoom: clamp(v.zoom, .1, 10, 1),
+		x: typeof v.x === "number" && isFinite(v.x) ? v.x : 0,
+		y: typeof v.y === "number" && isFinite(v.y) ? v.y : 0,
+		iw: typeof v.iw === "number" && v.iw > 0 ? v.iw : 0,
+		ih: typeof v.ih === "number" && v.ih > 0 ? v.ih : 0
 	};
 }
-/** Coerce an unknown persisted value into a valid ThemeConfig, falling back per-field. */
-function normalizeConfig(raw) {
+/** Coerce one persisted rule, or null when it lacks a usable id/slot. */
+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;
 	const c = r.color;
-	const color = Array.isArray(c) && c.length === 3 && c.every((x) => typeof x === "number" && isFinite(x)) ? [
+	const color = Array.isArray(c) && c.length === 3 && c.every((n) => typeof n === "number" && isFinite(n)) ? [
 		clamp(c[0], 0, 360, 220),
 		clamp(c[1], 0, 1, .55),
 		clamp(c[2], 0, 1, .25)
 	] : null;
-	const bgType = [
-		"image",
-		"video",
-		"mesh",
-		"shader",
-		"pattern"
-	].includes(r.backgroundType) ? r.backgroundType : DEFAULT_CONFIG.backgroundType;
-	const bgMode = [
+	const mode = [
 		"fit",
 		"fill",
 		"stretch",
 		"tile",
 		"center"
-	].includes(r.bgMode) ? r.bgMode : DEFAULT_CONFIG.bgMode;
-	const gen = r.generatedBg && typeof r.generatedBg === "object" ? r.generatedBg : null;
-	const generatedBg = gen && gen.type === bgType ? normalizeGeneratedBg(r.generatedBg) : null;
-	const legacy = typeof r.opacity === "number" ? r.opacity : null;
+	].includes(r.bgMode) ? r.bgMode : "fit";
+	return {
+		id,
+		slot,
+		match: typeof r.match === "string" ? r.match : "",
+		enabled: r.enabled !== false,
+		color,
+		bgMode: mode,
+		wallpaperOpacity: clamp01(r.wallpaperOpacity, 1),
+		blur: clamp(r.blur, 0, 60, 0),
+		bgState: normalizeBgState(r.bgState)
+	};
+}
+/** Coerce an unknown persisted value into a valid ThemeConfig, falling back per-field. */
+function normalizeConfig(raw) {
+	const r = raw ?? {};
+	const rules = Array.isArray(r.rules) ? r.rules.map(normalizeRule).filter((x) => x !== null) : [];
 	const ops = r.opacities ?? {};
 	const bl = r.blurs ?? {};
 	const blurs = {};
@@ -177,58 +130,69 @@ function normalizeConfig(raw) {
 		"input"
 	]) blurs[k] = clamp(bl[k], 0, 60, DEFAULT_CONFIG.blurs[k]);
 	return {
-		color,
+		rules,
 		opacities: {
-			bg: clamp(ops.bg, 0, 1, legacy ?? DEFAULT_CONFIG.opacities.bg),
-			sidebar: clamp(ops.sidebar, 0, 1, legacy !== null ? Math.min(1, legacy + .08) : DEFAULT_CONFIG.opacities.sidebar),
-			card: clamp(ops.card, 0, 1, DEFAULT_CONFIG.opacities.card),
-			input: clamp(ops.input, 0, 1, DEFAULT_CONFIG.opacities.input)
+			bg: clamp01(ops.bg, DEFAULT_CONFIG.opacities.bg),
+			sidebar: clamp01(ops.sidebar, DEFAULT_CONFIG.opacities.sidebar),
+			card: clamp01(ops.card, DEFAULT_CONFIG.opacities.card),
+			input: clamp01(ops.input, DEFAULT_CONFIG.opacities.input)
 		},
 		blurs,
-		settingsOpacity: clamp(r.settingsOpacity, 0, 1, DEFAULT_CONFIG.settingsOpacity),
-		wallpaperOpacity: clamp(r.wallpaperOpacity, 0, 1, DEFAULT_CONFIG.wallpaperOpacity),
-		blur: clamp(r.blur, 0, 60, DEFAULT_CONFIG.blur),
-		bgState: normalizeBgState(r.bgState ?? {}),
-		videoBgState: normalizeBgState(r.videoBgState ?? {}),
-		backgroundType: bgType,
-		bgMode,
-		videoMime: typeof r.videoMime === "string" ? r.videoMime : null,
-		generatedBg,
-		regenerateOnReload: typeof r.regenerateOnReload === "boolean" ? r.regenerateOnReload : DEFAULT_CONFIG.regenerateOnReload,
-		chatTextOpacity: clamp(r.chatTextOpacity, 0, 1, DEFAULT_CONFIG.chatTextOpacity),
-		trajectoryOpacity: clamp(r.trajectoryOpacity, 0, 1, DEFAULT_CONFIG.trajectoryOpacity)
+		settingsOpacity: clamp01(r.settingsOpacity, DEFAULT_CONFIG.settingsOpacity),
+		chatTextOpacity: clamp01(r.chatTextOpacity, DEFAULT_CONFIG.chatTextOpacity),
+		trajectoryOpacity: clamp01(r.trajectoryOpacity, DEFAULT_CONFIG.trajectoryOpacity)
 	};
 }
-function normalizeGeneratedBg(p) {
-	if (p.type === "mesh") return {
-		type: "mesh",
-		seed: typeof p.seed === "number" ? p.seed : 0,
-		scale: clamp(p.scale, .3, 3, 1),
-		intensity: clamp(p.intensity, 0, 1, .6)
-	};
-	if (p.type === "shader") return {
-		type: "shader",
-		preset: [
-			"aurora",
-			"nebula",
-			"noise"
-		].includes(p.preset) ? p.preset : "aurora",
-		speed: clamp(p.speed, 0, 2, .3),
-		scale: clamp(p.scale, .3, 3, 1),
-		seed: typeof p.seed === "number" ? Math.floor(p.seed) : 0
-	};
-	if (p.type === "pattern") return {
-		type: "pattern",
-		preset: [
-			"dots",
-			"waves",
-			"poly"
-		].includes(p.preset) ? p.preset : "dots",
-		density: clamp(p.density, 0, 1, .5),
-		scale: clamp(p.scale, .3, 3, 1),
-		seed: typeof p.seed === "number" ? Math.floor(p.seed) : 0
+/**
+* One-shot migration of the pre-0.3 store.
+*
+* Anything without a `rules` array is an old config: its single wallpaper
+* becomes rule 1 (`m1`, empty match = pure fallback) carrying the old color,
+* layout mode, opacity, blur and framing, and the remaining legacy files
+* (background video, upload temp) are removed. Idempotent: the rewritten config
+* carries `rules`, so the next read short-circuits.
+*/
+async function migrateLegacy(raw) {
+	const r = raw ?? {};
+	if (Array.isArray(r.rules)) return r;
+	const hasWallpaper = await exists(legacyWallpaperPath());
+	if (Object.keys(r).length === 0 && !hasWallpaper) return { rules: [] };
+	if (hasWallpaper) {
+		const target = imagePath("m1");
+		try {
+			await rm(target, { force: true });
+			await rename(legacyWallpaperPath(), target);
+		} catch (e) {
+			console.warn("dsh-background-by-model: could not adopt the legacy wallpaper", e);
+		}
+	}
+	for (const f of LEGACY_FILES) try {
+		await rm(dshHomePath(DATA_DIR, f), { force: true });
+	} catch {}
+	const next = {
+		rules: [{
+			id: "m1",
+			slot: "m1",
+			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 ?? {}
+		}],
+		opacities: r.opacities,
+		blurs: r.blurs,
+		settingsOpacity: r.settingsOpacity,
+		chatTextOpacity: r.chatTextOpacity,
+		trajectoryOpacity: r.trajectoryOpacity
 	};
-	return null;
+	try {
+		await writeFile(configPath(), JSON.stringify(next, null, 2), "utf8");
+	} catch (e) {
+		console.warn("dsh-background-by-model: could not rewrite the migrated config", e);
+	}
+	return next;
 }
 async function ensureDir() {
 	try {
@@ -239,12 +203,13 @@ async function ensureDir() {
 }
 async function readConfig() {
 	await ensureDir();
+	let raw = {};
 	try {
-		const raw = await readFile(configPath(), "utf8");
-		return normalizeConfig(JSON.parse(raw));
+		raw = JSON.parse(await readFile(configPath(), "utf8"));
 	} catch {
-		return { ...DEFAULT_CONFIG };
+		raw = {};
 	}
+	return normalizeConfig(await migrateLegacy(raw));
 }
 async function writeConfig(config) {
 	await ensureDir();
@@ -256,61 +221,72 @@ async function writeConfig(config) {
 		return false;
 	}
 }
-async function readWallpaper() {
+/** Sniff an image's MIME from its leading magic bytes (defaults to JPEG). */
+function sniffImageMime(buf) {
+	if (buf.length >= 4 && buf[0] === 137 && buf[1] === 80 && buf[2] === 78 && buf[3] === 71) return "image/png";
+	if (buf.length >= 3 && buf[0] === 255 && buf[1] === 216 && buf[2] === 255) return "image/jpeg";
+	if (buf.length >= 6 && buf[0] === 71 && buf[1] === 73 && buf[2] === 70) return "image/gif";
+	if (buf.length >= 12 && buf[0] === 82 && buf[1] === 73 && buf[2] === 70 && buf[3] === 70 && buf[8] === 87 && buf[9] === 69 && buf[10] === 66 && buf[11] === 80) return "image/webp";
+	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. */
+async function readImage(slot) {
 	try {
-		return `data:image/jpeg;base64,${(await readFile(wallpaperPath())).toString("base64")}`;
+		const buf = await readFile(imagePath(slot));
+		return `data:${sniffImageMime(buf)};base64,${buf.toString("base64")}`;
 	} catch {
 		return null;
 	}
 }
-/** Persist a wallpaper (null removes it); false keeps the previous file. */
-async function writeWallpaper(dataUrl) {
+/** Persist one rule image (null removes it); false keeps the previous file. */
+async function writeImage(slot, dataUrl) {
 	await ensureDir();
 	try {
 		if (dataUrl === null) {
-			await rm(wallpaperPath(), { force: true });
+			await rm(imagePath(slot), { force: true });
 			return true;
 		}
 		const m = /^data:image\/[a-zA-Z0-9.+-]+;base64,([A-Za-z0-9+/=]+)$/.exec(dataUrl);
 		if (!m) return false;
-		await writeFile(wallpaperPath(), Buffer.from(m[1], "base64"));
+		await writeFile(imagePath(slot), Buffer.from(m[1], "base64"));
 		return true;
 	} catch (e) {
-		console.error(`dsh-background-by-model: failed to write "${WALLPAPER_FILE}"`, e);
+		console.error(`dsh-background-by-model: failed to write the image for slot "${slot}"`, e);
 		return false;
 	}
 }
-/** Sniff an image's MIME from its leading magic bytes (defaults to JPEG). */
-function sniffImageMime(buf) {
-	if (buf.length >= 4 && buf[0] === 137 && buf[1] === 80 && buf[2] === 78 && buf[3] === 71) return "image/png";
-	if (buf.length >= 3 && buf[0] === 255 && buf[1] === 216 && buf[2] === 255) return "image/jpeg";
-	if (buf.length >= 6 && buf[0] === 71 && buf[1] === 73 && buf[2] === 70) return "image/gif";
-	if (buf.length >= 12 && buf[0] === 82 && buf[1] === 73 && buf[2] === 70 && buf[3] === 70 && buf[8] === 87 && buf[9] === 69 && buf[10] === 66 && buf[11] === 80) return "image/webp";
-	return "image/jpeg";
+/** Every image slot currently stored on disk. */
+async function listSlots() {
+	try {
+		return (await readdir(dataDir())).filter((name) => name.startsWith(IMAGE_PREFIX)).map((name) => name.slice(8)).filter((slot) => SLOT_RE.test(slot));
+	} catch {
+		return [];
+	}
 }
-/** Download a wallpaper from a network URL and persist it into the local
-*  wallpaper.jpg slot (replacing whatever was stored), so type switches,
-*  export and import keep working through the existing data-URL path.
-*  null removes the wallpaper. Returns { ok, dataUrl?, error? }. */
-async function writeWallpaperFromUrl(url) {
+/**
+* Download an image from a network URL into one slot (replacing its bytes).
+* Returns { ok, dataUrl?, error? }; never throws.
+*/
+async function fetchImageUrl(slot, url) {
 	if (url === null) {
-		const ok = await writeWallpaper(null);
+		const ok = await writeImage(slot, null);
 		return {
 			ok,
 			dataUrl: null,
 			error: ok ? void 0 : "remove failed"
 		};
 	}
-	let u;
+	let parsed;
 	try {
-		u = new URL(url);
+		parsed = new URL(url);
 	} catch {
 		return {
 			ok: false,
 			error: "invalid url"
 		};
 	}
-	if (u.protocol !== "http:" && u.protocol !== "https:") return {
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return {
 		ok: false,
 		error: "unsupported scheme"
 	};
@@ -360,7 +336,7 @@ async function writeWallpaperFromUrl(url) {
 		};
 	}
 	const dataUrl = `data:${sniffImageMime(buf)};base64,${buf.toString("base64")}`;
-	return await writeWallpaper(dataUrl) ? {
+	return await writeImage(slot, dataUrl) ? {
 		ok: true,
 		dataUrl
 	} : {
@@ -368,206 +344,82 @@ async function writeWallpaperFromUrl(url) {
 		error: "write failed"
 	};
 }
-async function videoUrl() {
-	return await findVideoFile() ? VIDEO_ROUTE : null;
-}
-/** Persist a video from a data URL (null removes every variant); only used
-*  for removal and small legacy/import payloads. */
-async function writeVideo(dataUrl) {
-	await ensureDir();
-	try {
-		if (dataUrl === null) {
-			for (const name of VIDEO_CANDIDATES) await rm(dshHomePath(DATA_DIR, name), { force: true });
-			return true;
-		}
-		const m = /^data:(video\/[a-zA-Z0-9.+-]+);base64,([A-Za-z0-9+/=]+)$/.exec(dataUrl);
-		if (!m) return false;
-		const target = videoPathFor(m[1]);
-		for (const name of VIDEO_CANDIDATES) {
-			const p = dshHomePath(DATA_DIR, name);
-			if (p !== target) await rm(p, { force: true });
-		}
-		await writeFile(target, Buffer.from(m[2], "base64"));
-		return true;
-	} catch (e) {
-		console.error("dsh-background-by-model: failed to write the background video", e);
-		return false;
-	}
-}
-/** Stream the stored video: correct MIME, no caching, Range answers so the
-*  browser can seek (snapshot capture does). */
-async function serveVideo(req, res) {
-	if (req.method !== "GET" && req.method !== "HEAD") {
-		res.writeHead(405, { "Content-Type": "application/json" });
-		res.end(JSON.stringify({
-			ok: false,
-			error: "video route only serves GET/HEAD; uploads need the plugin upload route — restart the web server to load it"
-		}));
-		return;
-	}
-	try {
-		const found = await findVideoFile();
-		if (found === null) {
-			res.writeHead(404);
-			res.end("no background video stored");
-			return;
-		}
-		const st = await stat(found.path);
-		const baseHeaders = {
-			"Content-Type": found.mime ?? "application/octet-stream",
-			"Accept-Ranges": "bytes",
-			"Cache-Control": "no-store"
-		};
-		const range = typeof req.headers.range === "string" ? req.headers.range.trim() : "";
-		const m = /^bytes=(\d*)-(\d*)$/.exec(range);
-		if (m !== null && (m[1] !== "" || m[2] !== "")) {
-			let start;
-			let end;
-			if (m[1] === "") {
-				const suffix = parseInt(m[2], 10);
-				start = Math.max(0, st.size - suffix);
-				end = st.size - 1;
-			} else {
-				start = parseInt(m[1], 10);
-				end = m[2] !== "" ? Math.min(parseInt(m[2], 10), st.size - 1) : st.size - 1;
-			}
-			if (start >= st.size || start > end) {
-				res.writeHead(416, { "Content-Range": `bytes */${st.size}` });
-				res.end();
-				return;
-			}
-			res.writeHead(206, {
-				...baseHeaders,
-				"Content-Range": `bytes ${start}-${end}/${st.size}`,
-				"Content-Length": end - start + 1
-			});
-			if (req.method === "HEAD") {
-				res.end();
-				return;
-			}
-			createReadStream(found.path, {
-				start,
-				end
-			}).pipe(res);
-			return;
-		}
-		res.writeHead(200, {
-			...baseHeaders,
-			"Content-Length": st.size
-		});
-		if (req.method === "HEAD") {
-			res.end();
-			return;
-		}
-		createReadStream(found.path).pipe(res);
-	} catch (e) {
-		console.error("dsh-background-by-model: failed to serve the background video", e);
-		try {
-			res.writeHead(500);
-			res.end();
-		} catch {}
-	}
-}
-/** Accept a raw video upload (POST): pipe the body into a temp file, then
-*  rename it into the MIME-derived slot. Aborted transfers clean up. */
-async function handleVideoUpload(req, res) {
-	if (req.method !== "POST") {
-		res.writeHead(405);
-		res.end();
-		return;
-	}
-	const mime = (typeof req.headers["content-type"] === "string" ? req.headers["content-type"] : "").split(";")[0].trim();
-	if (!mime.startsWith("video/")) {
-		req.resume();
-		res.writeHead(415, { "Content-Type": "application/json" });
-		res.end(JSON.stringify({
-			ok: false,
-			error: "unsupported media type, expected video/*"
-		}));
-		return;
-	}
+/** The host's default model selection — the client's fallback when the
+*  per-session model services are unavailable. */
+function defaultModel(ctx) {
 	try {
-		await ensureDir();
-		const tmp = dshHomePath(DATA_DIR, UPLOAD_TMP);
-		const target = videoPathFor(mime);
-		const out = createWriteStream(tmp);
-		let failed = false;
-		const fail = () => {
-			if (failed) return;
-			failed = true;
-			out.destroy();
-			rm(tmp, { force: true });
+		const selection = (typeof ctx.get === "function" ? ctx.get("agentDefaultModel") : void 0)?.currentSelection?.();
+		if (selection && typeof selection.provider === "string" && typeof selection.model === "string") return {
+			provider: selection.provider,
+			model: selection.model
 		};
-		req.on("aborted", fail);
-		req.on("error", fail);
-		out.on("error", () => {
-			fail();
-			try {
-				res.writeHead(500);
-				res.end();
-			} catch {}
-		});
-		req.pipe(out);
-		out.on("finish", async () => {
-			if (failed) return;
-			try {
-				for (const name of VIDEO_CANDIDATES) {
-					const p = dshHomePath(DATA_DIR, name);
-					if (p !== target) await rm(p, { force: true });
-				}
-				await rm(target, { force: true });
-				await rename(tmp, target);
-				res.writeHead(200, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ ok: true }));
-			} catch (e) {
-				console.error("dsh-background-by-model: failed to finalize the uploaded video", e);
-				rm(tmp, { force: true });
-				try {
-					res.writeHead(500);
-					res.end();
-				} catch {}
-			}
-		});
-	} catch (e) {
-		console.error("dsh-background-by-model: failed to accept the video upload", e);
-		try {
-			res.writeHead(500);
-			res.end();
-		} catch {}
-	}
+	} catch {}
+	return null;
 }
 const NS = "dshBackgroundByModel";
 const RPC_CHANNEL = "/dsh-background-by-model";
 const RPC_BODY_MAX = 314572800;
 /** Dispatch one decoded RPC method to the matching persistence routine and
 *  return the wire `result` half of the server-response envelope. */
-async function handleRpcMethod(endpoint, payload) {
+async function handleRpcMethod(ctx, endpoint, payload) {
 	const method = endpoint.slice(`${NS}/`.length);
+	const rawSlot = payload?.slot;
+	const slot = typeof rawSlot === "string" && SLOT_RE.test(rawSlot) ? rawSlot : null;
 	try {
 		switch (method) {
 			case "read": return {
 				ok: true,
 				value: {
 					config: await readConfig(),
-					wallpaper: await readWallpaper(),
-					videoUrl: await videoUrl()
+					slots: await listSlots()
 				}
 			};
 			case "writeConfig": return {
 				ok: true,
 				value: await writeConfig(payload?.config ?? {})
 			};
-			case "setWallpaper": return {
-				ok: true,
-				value: await writeWallpaper(payload?.dataUrl ?? null)
-			};
-			case "setVideo": return {
-				ok: true,
-				value: await writeVideo(payload?.dataUrl ?? null)
-			};
-			case "setWallpaperUrl": return {
+			case "readImage":
+				if (slot === null) return {
+					ok: true,
+					value: { dataUrl: null }
+				};
+				return {
+					ok: true,
+					value: { dataUrl: await readImage(slot) }
+				};
+			case "writeImage":
+				if (slot === null) return {
+					ok: true,
+					value: false
+				};
+				return {
+					ok: true,
+					value: await writeImage(slot, payload?.dataUrl ?? null)
+				};
+			case "deleteImage":
+				if (slot === null) return {
+					ok: true,
+					value: false
+				};
+				return {
+					ok: true,
+					value: await writeImage(slot, null)
+				};
+			case "fetchImageUrl":
+				if (slot === null) return {
+					ok: true,
+					value: {
+						ok: false,
+						error: "bad slot"
+					}
+				};
+				return {
+					ok: true,
+					value: await fetchImageUrl(slot, payload?.url ?? null)
+				};
+			case "defaultModel": return {
 				ok: true,
-				value: await writeWallpaperFromUrl(payload?.url ?? null)
+				value: defaultModel(ctx)
 			};
 			default: return {
 				ok: false,
@@ -676,7 +528,7 @@ function apply(ctx) {
 					}));
 					return;
 				}
-				const result = await handleRpcMethod(endpoint, env.payload);
+				const result = await handleRpcMethod(ctx, endpoint, env.payload);
 				res.writeHead(200, { "Content-Type": "application/json" });
 				res.end(JSON.stringify({
 					type: "server-response",
@@ -685,16 +537,6 @@ function apply(ctx) {
 				}));
 			}
 		}), "dsh-background-by-model: rpc channel");
-		webCtx.effect(() => webCtx.webServer.register({
-			kind: "prefix",
-			path: VIDEO_ROUTE,
-			handler: serveVideo
-		}), "dsh-background-by-model: video route");
-		webCtx.effect(() => webCtx.webServer.register({
-			kind: "exact",
-			path: UPLOAD_ROUTE,
-			handler: handleVideoUpload
-		}), "dsh-background-by-model: upload route");
 	});
 }
 //#endregion