dsh-any-background 0.2.9 → 0.2.10

package/lib/client.js

@@ -12,9 +12,15 @@ window.__ModuleLoader__.load({
 			try {
 				return require("@deepseek-ai/dsh-client-store");
 			} catch {}
-			return require("@deepseek-ai/dsh-client-runtime/client");
+			try {
+				return require("@deepseek-ai/dsh-client-runtime/client");
+			} catch {
+				console.warn("dsh-any-background: no client store module resolved on this host; the settings panel will be disabled");
+				return null;
+			}
 		}
-		const defineStore = resolveStore().defineStore;
+		/** null when neither store package resolves on this host (see resolveStore). */
+		const defineStore = resolveStore()?.defineStore ?? null;
 		//#endregion
 		//#region src/client/i18n.ts
 		const NS = "settings.anyBg";
@@ -57,6 +63,9 @@ window.__ModuleLoader__.load({
 			fontEnabled: "启用字体",
 			fontNone: "未设置，使用宿主默认字体",
 			fontFail: "字体上传失败，请确认是有效的 ttf/otf/woff/woff2 文件",
+			uploadTooLarge: "文件过大，上限 {limit}",
+			bgUploadFail: "壁纸上传失败",
+			videoUploadFail: "视频上传失败，本次播放不会被保存",
 			strokeTitle: "文字描边",
 			strokeHint: "按区域为文字添加描边：粗细为 0 表示关闭，「自动」会生成与文字颜色相反的颜色，「主题色」跟随当前主题色。代码块与图标已自动豁免，多色语法不会糊成一团",
 			strokeWidth: "描边粗细",
@@ -243,6 +252,9 @@ window.__ModuleLoader__.load({
 			fontEnabled: "Font enabled",
 			fontNone: "None — host default",
 			fontFail: "Upload failed — make sure it is a valid ttf/otf/woff/woff2 file",
+			uploadTooLarge: "File is too large (limit {limit})",
+			bgUploadFail: "Wallpaper upload failed",
+			videoUploadFail: "Video upload failed — this playback will not be saved",
 			strokeTitle: "Text outline",
 			strokeHint: "Outline text per region: width 0 turns it off, \"auto\" picks the inverse of the text color, and \"theme\" follows the current accent. Code blocks and icons are exempted automatically, so multi-color syntax never smears",
 			strokeWidth: "Outline width",
@@ -1117,36 +1129,73 @@ window.__ModuleLoader__.load({
 				error: v?.error ?? "failed"
 			};
 		}
+		/** Map a refused upload response onto an outcome. The body has to be read: the
+		*  node half names the reason there, and an oversized transfer answers
+		*  `413 { ok:false, error:'too large', limit:'100 MB' }`. Checking `res.ok`
+		*  alone threw that away, so an oversized upload surfaced as a bare failure —
+		*  or, on the wallpaper path, as nothing at all. */
+		async function refusedUpload(res) {
+			const body = await res.json().catch(() => null);
+			if (body?.error === "too large") return {
+				ok: false,
+				refusal: {
+					kind: "too-large",
+					status: res.status,
+					limit: typeof body.limit === "string" ? body.limit : void 0
+				}
+			};
+			return {
+				ok: false,
+				refusal: {
+					kind: "http",
+					status: res.status
+				}
+			};
+		}
+		/** Localized description of a refusal for the panel's toast. `fallbackKey` is
+		*  the caller's own "…upload failed" string, used for anything that is not a
+		*  size refusal. */
+		function uploadRefusalText(o, t, fallbackKey) {
+			if (o.refusal?.kind === "too-large") {
+				const limit = o.refusal.limit ?? "";
+				return t("uploadTooLarge").split("{limit}").join(limit);
+			}
+			if (o.refusal !== void 0) return `${t(fallbackKey)} (http ${o.refusal.status})`;
+			return t(fallbackKey);
+		}
 		/** Upload a video's raw bytes over HTTP (MIME in Content-Type, body untouched
 		*  — no base64 inflation that would blow the RPC body limit on large clips). */
 		async function uploadVideo(blob, mime) {
 			try {
-				return (await fetch(VIDEO_UPLOAD_URL, {
+				const res = await fetch(VIDEO_UPLOAD_URL, {
 					method: "POST",
 					headers: { "Content-Type": mime || "application/octet-stream" },
 					body: blob
-				})).ok;
+				});
+				return res.ok ? { ok: true } : await refusedUpload(res);
 			} catch (e) {
 				console.warn("dsh-any-background: video upload failed", e);
-				return false;
+				return { ok: false };
 			}
 		}
 		/** Upload a wallpaper's raw bytes over HTTP — same streaming model as videos,
 		*  original pixels preserved, zero base64 round-trips. */
 		async function uploadWallpaper(blob) {
 			try {
-				return (await fetch(WALLPAPER_UPLOAD_URL, {
+				const res = await fetch(WALLPAPER_UPLOAD_URL, {
 					method: "POST",
 					headers: { "Content-Type": blob.type || "image/jpeg" },
 					body: blob
-				})).ok;
+				});
+				return res.ok ? { ok: true } : await refusedUpload(res);
 			} catch (e) {
 				console.warn("dsh-any-background: wallpaper upload failed", e);
-				return false;
+				return { ok: false };
 			}
 		}
 		/** Upload a custom font's raw bytes over HTTP; resolves the sniffed MIME on
-		*  success (the server validates the container from magic bytes) or null. */
+		*  success, or a refusal the caller can report (an oversized font used to be
+		*  indistinguishable from a corrupt one). */
 		async function uploadFont(blob) {
 			try {
 				const res = await fetch(FONT_UPLOAD_URL, {
@@ -1154,12 +1203,15 @@ window.__ModuleLoader__.load({
 					headers: { "Content-Type": blob.type || "application/octet-stream" },
 					body: blob
 				});
-				if (!res.ok) return null;
+				if (!res.ok) return await refusedUpload(res);
 				const data = await res.json().catch(() => null);
-				return typeof data?.mime === "string" ? data.mime : "font/ttf";
+				return {
+					ok: true,
+					mime: typeof data?.mime === "string" ? data.mime : "font/ttf"
+				};
 			} catch (e) {
 				console.warn("dsh-any-background: font upload failed", e);
-				return null;
+				return { ok: false };
 			}
 		}
 		/** Remove the stored custom font (server deletes every variant + clears the
@@ -1340,6 +1392,12 @@ window.__ModuleLoader__.load({
 				v
 			];
 		}
+		/** Format an RGB triple as a lowercase hex string. Channels are rounded: some
+		*  callers feed float channels and a fractional byte would produce invalid
+		*  hex. */
+		function rgbToHex(rgb) {
+			return "#" + rgb.map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
+		}
 		let tokensCacheKey = "";
 		let tokensCache = null;
 		/**
@@ -2483,9 +2541,15 @@ window.__ModuleLoader__.load({
 			wpController = null;
 		}
 		/** Register a callback fired once a generated snapshot is ready (so the caller
-		*  can re-sync the settings preview / store). */
+		*  can re-sync the settings preview / store). Returns an unsubscribe: HMR
+		*  re-runs apply and would otherwise leave the previous apply's closure as the
+		*  live listener (a stale this-session callback invoked by a lingering
+		*  controller). */
 		function onGeneratedSnapshot(cb) {
 			snapshotListener = cb;
+			return () => {
+				if (snapshotListener === cb) snapshotListener = null;
+			};
 		}
 		function ensureTokenStyle() {
 			if (tokenStyleEl?.isConnected) return tokenStyleEl;
@@ -2724,6 +2788,18 @@ window.__ModuleLoader__.load({
 		}
 		/** Write every group's stroke width/color variables + the two column strokes.
 		*  Called from applyWp so palette/verdict changes re-derive 'auto'/'theme'. */
+		/** Write (or clear) one column's inline text stroke. The stroke rides inline
+		*  styles and is fully removed at width 0 so nothing lingers after the slider
+		*  resets. */
+		function applyInlineStroke(el, s) {
+			if (s.width > 0) {
+				el.style.setProperty("-webkit-text-stroke", `${s.width}px ${strokeColor(s)}`);
+				el.style.setProperty("paint-order", "stroke fill");
+			} else {
+				el.style.removeProperty("-webkit-text-stroke");
+				el.style.removeProperty("paint-order");
+			}
+		}
 		function applyStrokes() {
 			const strokes = rStrokes();
 			const root = document.documentElement;
@@ -2735,15 +2811,7 @@ window.__ModuleLoader__.load({
 			discoverParts();
 			for (const g of STROKE_INLINE_GROUPS) {
 				const el = g === "bg" ? centerEl : sidebarEl;
-				if (el === null) continue;
-				const s = strokes[g];
-				if (s.width > 0) {
-					el.style.setProperty("-webkit-text-stroke", `${s.width}px ${strokeColor(s)}`);
-					el.style.setProperty("paint-order", "stroke fill");
-				} else {
-					el.style.removeProperty("-webkit-text-stroke");
-					el.style.removeProperty("paint-order");
-				}
+				if (el !== null) applyInlineStroke(el, strokes[g]);
 			}
 		}
 		/** Live per-group stroke update during slider drag (no full re-apply). */
@@ -2756,13 +2824,7 @@ window.__ModuleLoader__.load({
 			discoverParts();
 			const el = part === "bg" ? centerEl : sidebarEl;
 			if (el === null) return;
-			if (s.width > 0) {
-				el.style.setProperty("-webkit-text-stroke", `${s.width}px ${strokeColor(s)}`);
-				el.style.setProperty("paint-order", "stroke fill");
-			} else {
-				el.style.removeProperty("-webkit-text-stroke");
-				el.style.removeProperty("paint-order");
-			}
+			applyInlineStroke(el, s);
 		}
 		/** Teardown only: drop every stroke variable and column inline stroke. */
 		function removeStrokes() {
@@ -2867,27 +2929,35 @@ window.__ModuleLoader__.load({
 			if (px > 0) document.documentElement.style.setProperty("--dsh-any-blur-panel", `blur(${px}px)`);
 			else document.documentElement.style.removeProperty("--dsh-any-blur-panel");
 		}
-		function applySettingsOverrides(op) {
+		/** Re-scope one surface group's layer tokens onto plugin-owned variables so a
+		*  dedicated slider owns its alpha (the host has no per-surface opacity). The
+		*  settings group additionally retints its dialog surface variable. Always
+		*  written explicitly — including at 100% — so removing a slider's effect means
+		*  writing 1, not deleting the variable (the style rules below have no fallback
+		*  and would otherwise resolve the body tokens that applyCustomTokens rewrote
+		*  with the homepage card alpha). */
+		function applyLayerOverrides(prefix, op, surface) {
 			const [h, s, l] = rColor();
 			const tokens = genTokens(h, s, l, rColorScheme()).tokens;
-			const layer1 = tokens["--dsw-alias-bg-layer-1"];
-			const layer2 = tokens["--dsw-alias-bg-layer-2"];
-			const layer3 = tokens["--dsw-alias-bg-layer-3"];
-			if (layer2 !== void 0) document.documentElement.style.setProperty("--dsh-any-bg-settings-surface", toRgba(layer2, op));
-			if (layer1 !== void 0) document.documentElement.style.setProperty("--dsh-any-bg-settings-layer-1", toRgba(layer1, op));
-			if (layer2 !== void 0) document.documentElement.style.setProperty("--dsh-any-bg-settings-layer-2", toRgba(layer2, op));
-			if (layer3 !== void 0) document.documentElement.style.setProperty("--dsh-any-bg-settings-layer-3", toRgba(layer3, op));
+			if (surface) {
+				const surfaceColor = tokens["--dsw-alias-bg-layer-2"];
+				if (surfaceColor !== void 0) document.documentElement.style.setProperty(`${prefix}-surface`, toRgba(surfaceColor, op));
+			}
+			for (const layer of [
+				1,
+				2,
+				3
+			]) {
+				const c = tokens[`--dsw-alias-bg-layer-${layer}`];
+				if (c !== void 0) document.documentElement.style.setProperty(`${prefix}-layer-${layer}`, toRgba(c, op));
+			}
+		}
+		function applySettingsOverrides(op) {
+			applyLayerOverrides("--dsh-any-bg-settings", op, true);
 		}
 		const TRAJECTORY_STYLE_RULE = "[data-conversation-composer-overlay]{--dsw-alias-bg-layer-1:var(--dsh-any-traj-layer-1);--dsw-alias-bg-layer-2:var(--dsh-any-traj-layer-2);--dsw-alias-bg-layer-3:var(--dsh-any-traj-layer-3)}";
 		function applyTrajectoryOverrides(op) {
-			const [h, s, l] = rColor();
-			const tokens = genTokens(h, s, l, rColorScheme()).tokens;
-			const layer1 = tokens["--dsw-alias-bg-layer-1"];
-			const layer2 = tokens["--dsw-alias-bg-layer-2"];
-			const layer3 = tokens["--dsw-alias-bg-layer-3"];
-			if (layer1 !== void 0) document.documentElement.style.setProperty("--dsh-any-traj-layer-1", toRgba(layer1, op));
-			if (layer2 !== void 0) document.documentElement.style.setProperty("--dsh-any-traj-layer-2", toRgba(layer2, op));
-			if (layer3 !== void 0) document.documentElement.style.setProperty("--dsh-any-traj-layer-3", toRgba(layer3, op));
+			applyLayerOverrides("--dsh-any-traj", op, false);
 		}
 		/** Register a callback fired when a wallpaper-extracted theme color is
 		*  adopted by the auto-adaptation path, so the section can re-register the
@@ -2896,6 +2966,9 @@ window.__ModuleLoader__.load({
 		let colorAdoptedListener = null;
 		function onColorAdopted(cb) {
 			colorAdoptedListener = cb;
+			return () => {
+				if (colorAdoptedListener === cb) colorAdoptedListener = null;
+			};
 		}
 		/** Apply the theme color: use the saved pick directly, or fall back to
 		*  extracting a dominant color from the current wallpaper. */
@@ -2911,8 +2984,8 @@ window.__ModuleLoader__.load({
 					if (hsl && rWp() === url) {
 						cfg.color = hsl;
 						colorAdoptedListener?.(hsl);
+						applyWp();
 					}
-					applyWp();
 				});
 			} else applyWp();
 		}
@@ -2944,7 +3017,7 @@ window.__ModuleLoader__.load({
 		*  preserving the user's scale/intensity/speed/density/preset choices. */
 		function regenerateGeneratedBg() {
 			const params = cfg.generatedBg;
-			if (!params || cfg.backgroundType === "image") return;
+			if (!params || cfg.backgroundType === "image" || cfg.backgroundType === "video") return;
 			cfg.generatedBg = {
 				...params,
 				seed: randomSeed()
@@ -2967,9 +3040,10 @@ window.__ModuleLoader__.load({
 				wpEl.appendChild(wpController.canvas);
 			}
 			requestAnimationFrame(() => {
-				if (!wpController) return;
 				const controller = wpController;
+				if (controller === null) return;
 				const frame = controller.snapshot();
+				if (wpController !== controller) return;
 				setWpUrl(frame);
 				applyWp();
 				snapshotListener?.();
@@ -2996,35 +3070,36 @@ window.__ModuleLoader__.load({
 			partBlurStyleEl.textContent = PART_BLUR_RULE;
 			document.head.appendChild(partBlurStyleEl);
 		}
-		/** Find one direct child of `frame` whose `[data-rightbar-col]` marker matches.
-		*  The rightbar is its own grid track, NOT a "details" twin of the center
-		*  column, so it must never receive the main-bg tint or blur underlay. */
-		function findRightbarInFrame(frame) {
-			for (let i = 0; i < frame.children.length; i++) {
-				const child = frame.children[i];
-				if (child instanceof HTMLElement && child.dataset.rightbarCol !== void 0) return child;
-			}
-			return null;
-		}
 		function discoverParts() {
 			const overlay = document.querySelector("[data-shell-overlay]");
 			if (overlay === null) return;
 			const frame = overlay.parentElement;
 			if (frame === null) return;
 			frameEl = frame;
-			rightEl = findRightbarInFrame(frame);
-			const idx = Array.from(frame.children).indexOf(overlay);
-			if (rightEl !== null) {
-				const rightIdx = Array.from(frame.children).indexOf(rightEl);
-				sidebarEl = frame.children[rightIdx - 2] ?? null;
-				centerEl = frame.children[rightIdx - 1] ?? null;
+			let overlayIdx = -1;
+			let rightIdx = -1;
+			let right = null;
+			const children = frame.children;
+			for (let i = 0; i < children.length; i++) {
+				const child = children[i];
+				if (child === overlay) overlayIdx = i;
+				else if (child instanceof HTMLElement && child.dataset.rightbarCol !== void 0) {
+					right = child;
+					rightIdx = i;
+				}
+			}
+			rightEl = right;
+			if (right !== null) {
+				sidebarEl = children[rightIdx - 2] ?? null;
+				centerEl = children[rightIdx - 1] ?? null;
 			} else {
-				sidebarEl = frame.children[idx - 3] ?? null;
-				centerEl = frame.children[idx - 2] ?? null;
+				sidebarEl = children[overlayIdx - 3] ?? null;
+				centerEl = children[overlayIdx - 2] ?? null;
 			}
 		}
 		function setBlur(el, px) {
 			if (el === null) return;
+			if (px === 0 && !el.classList.contains(PART_BLUR_CLASS) && el.getAttribute("data-dab-pos-patched") !== "1") return;
 			const underlay = el.querySelector(`:scope > .${PART_UNDERLAY_CLASS}`);
 			if (px > 0) {
 				ensurePartBlurStyle();
@@ -3158,6 +3233,34 @@ window.__ModuleLoader__.load({
 			plain: true
 		}];
 		const viewTargets = VIEW_CARDS.map(() => null);
+		/** View specs whose real host marker has been seen at least once. Until a
+		*  marker is seen, its absence is ambiguous — "that view is not mounted" or
+		*  "this build has no such marker, keep running the generic fallback" — and the
+		*  pass has to keep probing. Once seen, absence can only mean the former, so the
+		*  pass may be skipped.
+		*
+		*  This matters because the two specs are two different MAIN VIEWS and only one
+		*  of them is mounted at a time (the host renders the main slot for the active
+		*  panel id, keyed by `entryKey` — see AppFrame's MainPanel). So "every surface
+		*  present" is never true during a normal session, and an all-or-nothing gate on
+		*  it silently never engages: that is exactly how the previous version of this
+		*  observer ended up running the full pass on every animation frame while
+		*  tokens streamed. */
+		const markerSeen = /* @__PURE__ */ new Set();
+		/** Resolve just the stable host markers for the view specs — one querySelector
+		*  each, no fallback heuristics. Cheap enough to run on every coalesced burst,
+		*  and enough to notice a view mounting/unmounting. */
+		function probeViewMarkers() {
+			const center = centerEl;
+			if (center === null || !document.body.contains(center)) return VIEW_CARDS.map(() => null);
+			return VIEW_CARDS.map((spec) => center.querySelector(spec.sel));
+		}
+		/** Whether the pass must run regardless of the value/identity signature. */
+		function needsPartsPass(markers) {
+			if (!columnsPresent()) return true;
+			if (markers.some((el, i) => el !== null && el !== viewTargets[i])) return true;
+			return VIEW_CARDS.some((spec, i) => spec.fallback === true && markers[i] === null && !markerSeen.has(i));
+		}
 		function isScrollableY(el) {
 			const oy = getComputedStyle(el).overflowY;
 			return oy === "auto" || oy === "scroll" || oy === "overlay";
@@ -3202,6 +3305,7 @@ window.__ModuleLoader__.load({
 			const marked = centerEl.querySelector(spec.sel);
 			const cached = viewTargets[idx];
 			if (marked !== null) {
+				markerSeen.add(idx);
 				if (cached !== null && cached !== marked) {
 					setBlur(cached, 0);
 					restoreCardHost(cached, spec.mark, spec.prev, spec.plain === true);
@@ -3337,15 +3441,48 @@ window.__ModuleLoader__.load({
 			syncTableFix();
 		}
 		let partsObserver = null;
+		let partsApplyRaf = 0;
+		/** Signature of the last blur+opacity pass we actually wrote to the DOM. */
+		let appliedPartsKey = "";
+		/** The surfaces the last pass styled, compared BY IDENTITY: the host can swap
+		*  a view element for a fresh one while the slider values stay identical, and
+		*  the value signature alone would then skip the pass and leave the new view
+		*  unstyled until a slider moves. */
+		let appliedTargets = [];
+		/** The four frame columns are mounted and still attached. These are the frame's
+		*  own children (see the host's AppFrame: sidebar / center / rightbar carrying
+		*  `data-rightbar-col` / the overlay), so they exist as soon as the shell does —
+		*  unlike the per-view cards below, which come and go with the active view. */
+		function columnsPresent() {
+			return frameEl !== null && sidebarEl !== null && centerEl !== null && rightEl !== null && document.body.contains(frameEl) && document.body.contains(centerEl);
+		}
+		/** Snapshot of every surface the pass would style, for the identity check. */
+		function targetsNow() {
+			return [
+				frameEl,
+				sidebarEl,
+				centerEl,
+				rightEl,
+				...viewTargets
+			];
+		}
 		/** Watch for the AppFrame mounting so persisted blurs land even when the shell
-		*  renders after this plugin's apply. Cheap: once all parts are found, the
-		*  callback returns. */
+		*  renders after this plugin's apply. */
 		function watchParts() {
 			if (partsObserver !== null || typeof MutationObserver === "undefined") return;
 			partsObserver = new MutationObserver(() => {
-				if (frameEl !== null && sidebarEl !== null && centerEl !== null && rightEl !== null && document.body.contains(frameEl) && viewTargets.every((el) => el !== null && document.body.contains(el))) return;
-				applyPartBlurs(rBlurs());
-				applyPartOpacities(rOps());
+				if (partsApplyRaf !== 0) return;
+				partsApplyRaf = requestAnimationFrame(() => {
+					partsApplyRaf = 0;
+					const blurs = rBlurs();
+					const ops = rOps();
+					const key = JSON.stringify([blurs, ops]);
+					if (!needsPartsPass(probeViewMarkers()) && key === appliedPartsKey && !targetsNow().some((el, i) => el !== appliedTargets[i])) return;
+					applyPartBlurs(blurs);
+					applyPartOpacities(ops);
+					appliedPartsKey = key;
+					appliedTargets = targetsNow();
+				});
 			});
 			partsObserver.observe(document.body, {
 				childList: true,
@@ -3355,6 +3492,13 @@ window.__ModuleLoader__.load({
 		function stopWatchingParts() {
 			partsObserver?.disconnect();
 			partsObserver = null;
+			if (partsApplyRaf !== 0) {
+				cancelAnimationFrame(partsApplyRaf);
+				partsApplyRaf = 0;
+			}
+			appliedPartsKey = "";
+			appliedTargets = [];
+			markerSeen.clear();
 		}
 		let themeObserver = null;
 		let themeRaf = 0;
@@ -3507,6 +3651,9 @@ window.__ModuleLoader__.load({
 		*  be re-registered through the host theme service. */
 		function onVerdictApplied(cb) {
 			verdictListener = cb;
+			return () => {
+				if (verdictListener === cb) verdictListener = null;
+			};
 		}
 		function applyVerdict(dark) {
 			if (rBgDark() === dark) return;
@@ -3634,6 +3781,8 @@ window.__ModuleLoader__.load({
 					clearVideoEl();
 					wpEl?.remove();
 					wpEl = null;
+					wpVerdict = null;
+					setBgDark(null);
 				}
 			} else if (cfg.backgroundType !== "image" && cfg.generatedBg) {
 				clearVideoEl();
@@ -3705,8 +3854,14 @@ window.__ModuleLoader__.load({
 			pendingOps = null;
 			tableFixStyleEl?.remove();
 			tableFixStyleEl = null;
+			partBlurStyleEl?.remove();
+			partBlurStyleEl = null;
 			removeStrokes();
 			removeFontFace();
+			imgNat = null;
+			lowResUrl = null;
+			lowResFor = "";
+			dragLow = false;
 			setBlur(frameEl, 0);
 			setBlur(sidebarEl, 0);
 			setBlur(centerEl, 0);
@@ -3842,7 +3997,10 @@ window.__ModuleLoader__.load({
 /* ── wheel card ──────────────────────────────────────────────────────────── */
 .dab-wheel-card{position:relative;display:flex;align-items:center;justify-content:center;gap:28px;flex-wrap:wrap;padding:24px 18px}
 .dab-wheel-glow{position:absolute;width:230px;height:230px;border-radius:50%;filter:blur(48px);opacity:.2;background:var(--c,#888);pointer-events:none;transition:background .4s ease}
-.dab-wheel{position:relative;cursor:crosshair;border-radius:50%;box-shadow:0 12px 32px -14px rgba(0,0,0,.4)}
+/* flex:none is load bearing, not cosmetic: the pointer maths reads client
+ * coordinates straight off this element's box, so any shrink below the 220px
+ * drawing surface would desynchronise the ring from the cursor. */
+.dab-wheel{position:relative;flex:none;cursor:crosshair;border-radius:50%;box-shadow:0 12px 32px -14px rgba(0,0,0,.4)}
 .dab-hint{font-size:11.5px;line-height:1.55;color:var(--dsw-alias-label-tertiary);padding:0 4px}
 
 /* ── precise color inputs ────────────────────────────────────────────────── */
@@ -3896,7 +4054,7 @@ window.__ModuleLoader__.load({
 .dab-slider::-moz-range-thumb{width:13px;height:13px;border-radius:50%;background:var(--dsw-alias-button-elevated-fill,#fff);border:2px solid var(--dsw-alias-brand-primary)}
 
 /* ── interface part cards ────────────────────────────────────────────────── */
-.dab-grid-parts{display:grid;grid-template-columns:repeat(auto-fill,minmax(256px,1fr));gap:13px}
+.dab-grid-parts{display:grid;grid-template-columns:repeat(auto-fill,minmax(min(240px,100%),1fr));gap:13px}
 .dab-part-head{display:flex;align-items:center;gap:11px;margin-bottom:14px}
 .dab-part-ico{width:32px;height:32px;flex:none;border-radius:10px;display:grid;place-items:center;color:var(--dsw-alias-brand-primary);background:var(--dsw-alias-bg-layer-2);background:color-mix(in srgb,var(--dsw-alias-brand-primary) 12%,transparent)}
 .dab-part-name{font-size:13.5px;font-weight:600}
@@ -3973,7 +4131,7 @@ window.__ModuleLoader__.load({
 .dab-spin{animation:dab-rotate .7s cubic-bezier(.3,.7,.3,1) 1}
 
 /* ── profile page ────────────────────────────────────────────────────────── */
-.dab-profile-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(238px,1fr));gap:13px}
+.dab-profile-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(220px,100%),1fr));gap:13px}
 .dab-profile-ico{width:38px;height:38px;border-radius:11px;display:grid;place-items:center;margin-bottom:13px;color:var(--dsw-alias-brand-primary);background:var(--dsw-alias-bg-layer-2);background:color-mix(in srgb,var(--dsw-alias-brand-primary) 12%,transparent)}
 .dab-profile-title{font-size:14px;font-weight:650}
 .dab-profile-desc{font-size:12px;color:var(--dsw-alias-label-tertiary);line-height:1.55;margin:5px 0 15px}
@@ -3982,7 +4140,7 @@ window.__ModuleLoader__.load({
 
 /* ── presets / profiles / schedule / rotation ────────────────────────────── */
 .dab-row-head{display:flex;align-items:center;justify-content:space-between;gap:12px}
-.dab-preset-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(150px,1fr));gap:10px}
+.dab-preset-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(min(150px,100%),1fr));gap:10px}
 .dab-preset{display:flex;flex-direction:column;align-items:flex-start;gap:3px;padding:12px;border:1.5px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-1);border-radius:13px;cursor:pointer;font:inherit;text-align:left;transition:border-color .25s,transform .25s,box-shadow .25s;animation:dab-row-in .34s cubic-bezier(.22,1,.36,1) both;animation-delay:calc(var(--i,0) * 45ms)}
 .dab-preset:hover{transform:translateY(-2px);border-color:var(--dsw-alias-brand-primary);box-shadow:0 8px 22px -12px rgba(0,0,0,.3)}
 .dab-preset-dot{width:22px;height:22px;border-radius:50%;margin-bottom:4px;box-shadow:inset 0 0 0 1px rgba(0,0,0,.12),0 4px 10px -4px rgba(0,0,0,.35);background:var(--dsw-alias-bg-layer-2);display:grid;place-items:center;color:var(--dsw-alias-label-tertiary)}
@@ -4009,7 +4167,7 @@ window.__ModuleLoader__.load({
 .dab-schedule-wrap.is-open{grid-template-rows:1fr;visibility:visible;transition:grid-template-rows .42s cubic-bezier(.22,1,.36,1)}
 .dab-schedule-clip{overflow:hidden;min-height:0;opacity:0;transition:opacity .28s ease}
 .dab-schedule-wrap.is-open .dab-schedule-clip{opacity:1;transition:opacity .32s ease .1s}
-.dab-schedule-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(220px,1fr));gap:16px;padding-top:12px}
+.dab-schedule-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(220px,100%),1fr));gap:16px;padding-top:12px}
 .dab-schedule-cell{min-width:0;animation:dab-row-in .34s cubic-bezier(.22,1,.36,1) both;animation-delay:calc(var(--i,0) * 60ms)}
 .dab-time-row{display:flex;flex-direction:column;gap:9px}
 .dab-time-label{display:flex;align-items:center;gap:7px;font-size:12px;color:var(--dsw-alias-label-secondary,var(--dsw-alias-label-tertiary))}
@@ -4045,6 +4203,9 @@ window.__ModuleLoader__.load({
 .dab-crash{display:flex;flex-direction:column;gap:10px;align-items:center;padding:28px 18px;border:1px solid var(--dsw-alias-border-l2);border-radius:16px}
 .dab-crash-title{font-size:15px;font-weight:650}
 .dab-crash-desc{font-size:12px;color:var(--dsw-alias-label-tertiary);text-align:center;line-height:1.5}
+/* The crash cause: readable, scrollable, and clipped to a few lines so a long
+ * stack cannot push the reset button off the panel. */
+.dab-crash-detail{margin:0;max-width:min(520px,80vw);max-height:132px;overflow:auto;padding:8px 10px;border-radius:8px;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);font-family:var(--dab-mono);font-size:10.5px;line-height:1.5;color:var(--dsw-alias-label-secondary,var(--dsw-alias-label-tertiary));text-align:left;white-space:pre-wrap;word-break:break-word}
 
 /* ── keyframes ───────────────────────────────────────────────────────────── */
 @keyframes dab-fade-in{from{opacity:0}to{opacity:1}}
@@ -4060,6 +4221,72 @@ window.__ModuleLoader__.load({
 @keyframes dab-zoom-in{from{opacity:0;transform:scale(.94) translateY(8px)}to{opacity:1;transform:none}}
 @keyframes dab-flow{to{background-position:300% 50%}}
 
+/* ── sidebar surface (a dsh-better-sidebar page) ─────────────────────────────
+ * Same shell, hosted in a panel that is handed a full-height column (the host's
+ * native tab body is height:100%) and whose width the user drags freely. So only
+ * THREE things are fixed here, all of them structural:
+ *   1. the shell fills the height and the page body owns the scroll
+ *      (flex:1 + min-height:0), so the panel stays one scrollable column instead
+ *      of pushing the whole tab into a scrollbar;
+ *   2. the nav is a rail ABOVE the page rather than beside it — a side rail would
+ *      spend 150px of a panel that is narrow by nature, and this way the page
+ *      keeps the full width for its own grids;
+ *   3. long tokens (paths, hex, URLs) may wrap instead of widening the panel.
+ *
+ * Everything else — grid columns, paddings, type scale, whether the cards lift on
+ * hover — is width-driven through the container queries below, which measure this
+ * shell (the .dab-root container, which declares container-type:inline-size) and
+ * not the viewport. A narrow sidebar compacts; a wide one falls back to the
+ * dialog's own spacing and multi-column grids, because at that point it *is* a
+ * dialog-sized surface. */
+[data-dab-surface="sidebar"].dab-root{height:100%;min-height:0;padding:12px 12px 0}
+[data-dab-surface="sidebar"] .dab-shell{display:flex;flex-direction:column;align-items:stretch;gap:11px;height:100%;min-height:0;max-width:none;padding-bottom:0}
+[data-dab-surface="sidebar"] .dab-nav{gap:0}
+[data-dab-surface="sidebar"] .dab-nav-list{flex-direction:row;gap:2px;overflow-x:auto;overflow-y:hidden;padding-bottom:1px}
+[data-dab-surface="sidebar"] .dab-nav-list::-webkit-scrollbar{display:none}
+[data-dab-surface="sidebar"] .dab-nav-ind{display:none}
+[data-dab-surface="sidebar"] .dab-nav-item{flex:none;height:32px;gap:7px;padding:0 10px;font-size:12px}
+[data-dab-surface="sidebar"] .dab-nav-item.is-active{background:var(--dsw-alias-bg-layer-2)}
+[data-dab-surface="sidebar"] .dab-page{flex:1;min-height:0;overflow-y:auto;overflow-x:hidden;padding-bottom:16px;scrollbar-width:thin}
+/* Last-resort safety for text that cannot wrap (paths, hex, URLs). */
+[data-dab-surface="sidebar"] .dab-hint,[data-dab-surface="sidebar"] .dab-part-name{overflow-wrap:anywhere}
+/* The panel's width is whatever the user dragged it to, so let the part cards
+ * fill as many columns as actually fit instead of hard-coding one. 170px is the
+ * narrowest a part card stays readable once its header can wrap (see the head
+ * rules below), which puts the second column at roughly a 380px panel — the
+ * default right-sidebar width. */
+[data-dab-surface="sidebar"] .dab-grid-parts{grid-template-columns:repeat(auto-fill,minmax(min(170px,100%),1fr));gap:12px}
+[data-dab-surface="sidebar"] .dab-types{grid-template-columns:repeat(auto-fit,minmax(min(150px,100%),1fr))}
+[data-dab-surface="sidebar"] .dab-card{padding:12px}
+[data-dab-surface="sidebar"] .dab-part-head{gap:8px;margin-bottom:10px}
+[data-dab-surface="sidebar"] .dab-part-ico{width:26px;height:26px;border-radius:8px}
+[data-dab-surface="sidebar"] .dab-part-name{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:12.5px}
+[data-dab-surface="sidebar"] .dab-part-badge{padding:2px 7px;font-size:10px}
+
+/* Narrow panel: tighten the chrome so the content still has room. */
+@container (max-width:539px){
+  [data-dab-surface="sidebar"] .dab-page{gap:11px}
+  [data-dab-surface="sidebar"] .dab-h1{font-size:17px}
+  [data-dab-surface="sidebar"] .dab-desc{font-size:12px}
+  [data-dab-surface="sidebar"] .dab-orb-wrap{width:96px;height:96px}
+  [data-dab-surface="sidebar"] .dab-wheel-card{padding:14px 10px;gap:16px}
+  [data-dab-surface="sidebar"] .dab-wheel-glow{width:170px;height:170px}
+  /* Lift-on-hover is a dialog affordance; in a cramped scrolling panel it only
+   * adds jitter under the cursor. */
+  [data-dab-surface="sidebar"] .dab-card-hover:hover{transform:none;box-shadow:none}
+}
+/* Roomy panel: behave like the dialog again — its spacing, its type scale, and
+ * multi-column grids (a smaller track minimum than the dialog, because the page
+ * here is a few hundred px narrower than a dialog's content column). */
+@container (min-width:540px){
+  [data-dab-surface="sidebar"] .dab-shell{gap:16px}
+  [data-dab-surface="sidebar"] .dab-page{gap:13px}
+  [data-dab-surface="sidebar"] .dab-nav-item{height:34px;font-size:12.5px;padding:0 12px}
+  /* The shared ≤620px rule flattens the type cards to one column, which is right
+   * for a narrow phone-width dialog but wasteful in a roomy panel. */
+  [data-dab-surface="sidebar"] .dab-types{grid-template-columns:repeat(auto-fit,minmax(180px,1fr))}
+}
+
 /* ── responsive & motion preferences ─────────────────────────────────────── */
 @container (max-width:620px){
   .dab-shell{grid-template-columns:1fr;gap:14px}
@@ -4074,6 +4301,30 @@ window.__ModuleLoader__.load({
 @container (min-width:621px){
   .dab-shell{grid-template-columns:158px minmax(0,1fr);gap:26px}
 }
+/* Phone: on a handset the settings dialog's content column shrinks to roughly
+ * the viewport, and the dialog-sized chrome (18px cards, 21px headings, a 118px
+ * orb, 24px paddings) stops fitting — cards end up wider than the column or the
+ * color row wraps into three cramped pieces. These are the same tightenings the
+ * sidebar surface applies at its own narrow widths, so a phone settings dialog
+ * and a narrow sidebar panel end up looking the same. */
+@container (max-width:480px){
+  .dab-shell{gap:10px}
+  .dab-page{gap:10px}
+  .dab-head{margin:0 0 2px}
+  .dab-h1{font-size:18px}
+  .dab-desc{font-size:12px}
+  .dab-card{padding:14px;border-radius:14px}
+  .dab-hero-accent{gap:16px}
+  .dab-orb-wrap{width:92px;height:92px}
+  .dab-wheel-card{padding:14px 10px;gap:16px}
+  .dab-wheel-glow{width:180px;height:180px}
+  /* Three fixed type-card columns need ~400px; two adaptive ones fit 320px. */
+  .dab-types{grid-template-columns:repeat(auto-fit,minmax(min(150px,100%),1fr))}
+  .dab-grid-parts{gap:11px}
+  .dab-part-head{margin-bottom:10px}
+  .dab-slider-block + .dab-slider-block{margin-top:10px}
+  .dab-footer{padding-top:10px}
+}
 @media (prefers-reduced-motion:reduce){
   .dab-root *,.dab-root *::before,.dab-root *::after{animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}
 }
@@ -4404,25 +4655,32 @@ window.__ModuleLoader__.load({
 				this.props.onReset?.();
 			};
 			render() {
-				if (this.state.error) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
-					className: "dab-crash",
-					children: [
-						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: "dab-crash-title",
-							children: this.props.t("crashTitle")
-						}),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: "dab-crash-desc",
-							children: this.props.t("crashDesc")
-						}),
-						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
-							type: "button",
-							className: "dab-btn",
-							onClick: this.reset,
-							children: this.props.t("crashReset")
-						})
-					]
-				});
+				if (this.state.error) {
+					const detail = this.state.error.stack ?? `${this.state.error.name}: ${this.state.error.message}`;
+					return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "dab-crash",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "dab-crash-title",
+								children: this.props.t("crashTitle")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "dab-crash-desc",
+								children: this.props.t("crashDesc")
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("pre", {
+								className: "dab-crash-detail",
+								children: detail
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: "dab-btn",
+								onClick: this.reset,
+								children: this.props.t("crashReset")
+							})
+						]
+					});
+				}
 				return this.props.children;
 			}
 		};
@@ -4571,6 +4829,10 @@ window.__ModuleLoader__.load({
 			}, [col]);
 			const pendingRef = (0, react.useRef)(null);
 			const rafRef = (0, react.useRef)(null);
+			/** Unmount-time cleanup for a drag that never saw its mouseup (panel closed
+			*  mid-drag): without it the document listeners stay attached forever and the
+			*  pending rAF keeps calling setState on a dead component. */
+			const dragCleanupRef = (0, react.useRef)(null);
 			const flushPending = (0, react.useCallback)(() => {
 				rafRef.current = null;
 				const p = pendingRef.current;
@@ -4612,13 +4874,25 @@ window.__ModuleLoader__.load({
 						schedule(colRef.current.hue, s, l);
 					}
 				};
-				const onUp = () => {
+				const stopDrag = () => {
 					document.removeEventListener("mousemove", onMove);
-					document.removeEventListener("mouseup", onUp);
+					document.removeEventListener("mouseup", stopDrag);
+					dragCleanupRef.current = null;
 				};
+				dragCleanupRef.current = stopDrag;
 				document.addEventListener("mousemove", onMove);
-				document.addEventListener("mouseup", onUp);
+				document.addEventListener("mouseup", stopDrag);
 			}, [schedule]);
+			(0, react.useEffect)(() => {
+				return () => {
+					if (rafRef.current !== null) {
+						cancelAnimationFrame(rafRef.current);
+						rafRef.current = null;
+					}
+					pendingRef.current = null;
+					dragCleanupRef.current?.();
+				};
+			}, []);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("canvas", {
 				ref: cvsRef,
 				width: WHEEL_SIZE,
@@ -4667,6 +4941,7 @@ window.__ModuleLoader__.load({
 					},
 					onChange: (e) => {
 						setText(e.target.value);
+						if (e.target.value === "") return;
 						const v = Number(e.target.value);
 						if (Number.isFinite(v)) onChange(clamp(v, min, max));
 					}
@@ -4783,9 +5058,6 @@ window.__ModuleLoader__.load({
 		//#region src/client/components/ColorPicker.tsx
 		const MAG_SIZE = 96;
 		const MAG_ZOOM = 8;
-		function toHex$1(rgb) {
-			return "#" + rgb.map((v) => v.toString(16).padStart(2, "0")).join("");
-		}
 		/**
 		* Eyedropper modal: shows the wallpaper full-bleed (no drag/zoom) and lets the
 		* user click any pixel to adopt it as the theme color. A magnifier circle
@@ -4815,7 +5087,7 @@ window.__ModuleLoader__.load({
 				canvas.height = imgRef.current.naturalHeight;
 				const ctx = canvas.getContext("2d");
 				if (ctx) ctx.drawImage(imgRef.current, 0, 0);
-			}, [ready]);
+			}, [ready, url]);
 			const sampleAt = (0, react.useCallback)((clientX, clientY) => {
 				const canvas = canvasRef.current;
 				if (!canvas) return null;
@@ -4930,14 +5202,14 @@ window.__ModuleLoader__.load({
 							height: 28,
 							borderRadius: 8,
 							border: "1px solid rgba(255,255,255,0.4)",
-							background: hover ? toHex$1(hover.rgb) : "transparent"
+							background: hover ? rgbToHex(hover.rgb) : "transparent"
 						} }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 							style: {
 								color: "#fff",
 								fontSize: 13,
 								fontFamily: "var(--dab-mono, monospace)"
 							},
-							children: hover ? `${toHex$1(hover.rgb)} · rgb(${hover.rgb.join(", ")})` : "—"
+							children: hover ? `${rgbToHex(hover.rgb)} · rgb(${hover.rgb.join(", ")})` : "—"
 						})]
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
@@ -5020,9 +5292,6 @@ window.__ModuleLoader__.load({
 				.58
 			]
 		];
-		function toHex(rgb) {
-			return "#" + rgb.map((v) => Math.round(v).toString(16).padStart(2, "0")).join("");
-		}
 		function ColorPage({ p, notify }) {
 			const { t, hue, sat, lit, setColor, extractColor, setSchemeOverride, useStore } = p;
 			const storeUrl = useStore((s) => s.url);
@@ -5037,7 +5306,7 @@ window.__ModuleLoader__.load({
 			];
 			const [h, s, l] = hsvToHsl(wheel[0], wheel[1], wheel[2]);
 			const [r, g, b] = hslToRgb(h, s, l);
-			const hex = toHex([
+			const hex = rgbToHex([
 				r,
 				g,
 				b
@@ -5167,7 +5436,7 @@ window.__ModuleLoader__.load({
 								type: "button",
 								className: `dab-swatch${on ? " is-on" : ""}`,
 								style: { background: `hsl(${sh} ${Math.round(ss * 100)}% ${Math.round(sl * 100)}%)` },
-								title: toHex(hslToRgb(sh, ss, sl)).toUpperCase(),
+								title: rgbToHex(hslToRgb(sh, ss, sl)).toUpperCase(),
 								onClick: () => setColor(...hslToHsv(sh, ss, sl))
 							}, i);
 						})
@@ -5242,15 +5511,16 @@ window.__ModuleLoader__.load({
 			const paint = (el, v) => {
 				el.style.setProperty("--pct", String((v - min) / (max - min) * 100));
 			};
+			const fmtRef = (0, react.useRef)(fmt);
+			fmtRef.current = fmt;
 			(0, react.useEffect)(() => {
 				if (inputRef.current) {
 					inputRef.current.value = String(def);
 					paint(inputRef.current, def);
 				}
-				if (valRef.current) valRef.current.textContent = fmt(def);
+				if (valRef.current) valRef.current.textContent = fmtRef.current(def);
 			}, [
 				def,
-				fmt,
 				min,
 				max
 			]);
@@ -5410,7 +5680,8 @@ window.__ModuleLoader__.load({
 			}
 		];
 		function InterfacePage({ p }) {
-			const { t, setOps, setBlurs, setSop, setPanelOp } = p;
+			const { t, setOps, setBlurs, setSop, setPanelOp, useStore } = p;
+			useStore((s) => s.metaRev);
 			const hasBetterSidebar = useBetterSidebar();
 			const parts = PARTS$1.filter((part) => !(part.isPanel && !hasBetterSidebar));
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("header", {
@@ -5617,7 +5888,7 @@ window.__ModuleLoader__.load({
 			}
 		}
 		function FontPage({ p, notify }) {
-			const { t, setFont, removeFont, setFontEnabled, setStrokes } = p;
+			const { t, setFont, removeFont, setFontEnabled, setStrokes, useStore } = p;
 			const hasBetterSidebar = useBetterSidebar();
 			const fileRef = (0, react.useRef)(null);
 			const [strokes, setStrokesState] = (0, react.useState)(() => rStrokes());
@@ -5627,6 +5898,15 @@ window.__ModuleLoader__.load({
 				name: null
 			}));
 			const [busy, setBusy] = (0, react.useState)(false);
+			const metaRev = useStore((s) => s.metaRev);
+			(0, react.useEffect)(() => {
+				setStrokesState(rStrokes());
+				setFontInfo((prev) => prev.mime === cfg.fontMime && prev.enabled === cfg.fontEnabled ? prev : {
+					mime: cfg.fontMime,
+					enabled: cfg.fontEnabled,
+					name: null
+				});
+			}, [metaRev]);
 			const hasFont = fontInfo.mime !== null;
 			const fontLabel = fontInfo.name ?? (fontInfo.mime !== null ? fontInfo.mime.replace("font/", "").toUpperCase() : t("fontNone"));
 			/** Write one group's stroke: cfg + live DOM now, disk on commit. `live`
@@ -5651,9 +5931,9 @@ window.__ModuleLoader__.load({
 					...fontInfo,
 					name: file.name
 				});
-				const ok = await setFont(file);
+				const outcome = await setFont(file);
 				setBusy(false);
-				if (ok) setFontInfo({
+				if (outcome.ok) setFontInfo({
 					mime: cfg.fontMime,
 					enabled: cfg.fontEnabled,
 					name: file.name
@@ -5664,7 +5944,7 @@ window.__ModuleLoader__.load({
 						enabled: cfg.fontEnabled,
 						name: null
 					});
-					notify(t("fontFail"), false);
+					notify(uploadRefusalText(outcome, t, "fontFail"), false);
 				}
 			};
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
@@ -5878,6 +6158,19 @@ window.__ModuleLoader__.load({
 			});
 			const containerRef = (0, react.useRef)(null);
 			const imgRef = (0, react.useRef)(null);
+			/**
+			* The overlay node is held in STATE rather than a plain ref, so the listener
+			* effect below re-runs the moment it actually exists.
+			*
+			* This is not a style choice. Everything here renders through <Portal>, which
+			* returns null on its first render — its own effect has to create the host
+			* node under <html> first. A plain ref is therefore still null when a
+			* mount-only effect runs, and an effect whose deps never change again attaches
+			* nothing, ever. That is exactly how the touch handlers below ended up dead on
+			* real phones: the wheel handler only survived because its deps churn on every
+			* zoom/pan, so the wallpaper's img.onload re-ran it once and wired it up.
+			*/
+			const [overlayEl, setOverlayEl] = (0, react.useState)(null);
 			const dragRef = (0, react.useRef)({
 				active: false,
 				sx: 0,
@@ -5885,6 +6178,16 @@ window.__ModuleLoader__.load({
 				spx: 0,
 				spy: 0
 			});
+			/** Unmount-time cleanup for a drag that never saw its mouseup (editor closed
+			*  mid-drag): without it the document listeners stay attached forever and
+			*  keep calling setPos on a dead component. */
+			const dragStopRef = (0, react.useRef)(null);
+			/** Set once a gesture actually moved, so the click that follows a drag is not
+			*  mistaken for a tap on the backdrop (mousedown and mouseup in different
+			*  subtrees make the click land on the overlay, i.e. "outside"). Reset at the
+			*  start of every gesture — touchstart / mousedown / wheel — so it can only
+			*  ever describe the gesture that just ended, never an earlier one. */
+			const movedRef = (0, react.useRef)(false);
 			const viewRef = (0, react.useRef)({
 				zoom,
 				pos
@@ -5930,6 +6233,7 @@ window.__ModuleLoader__.load({
 			]);
 			const onDown = (0, react.useCallback)((e) => {
 				e.preventDefault();
+				movedRef.current = false;
 				dragRef.current = {
 					active: true,
 					sx: e.clientX,
@@ -5939,58 +6243,50 @@ window.__ModuleLoader__.load({
 				};
 				const onMove = (ev) => {
 					if (!dragRef.current.active) return;
+					if (Math.abs(ev.clientX - dragRef.current.sx) > 4 || Math.abs(ev.clientY - dragRef.current.sy) > 4) movedRef.current = true;
 					setPos({
 						x: dragRef.current.spx + ev.clientX - dragRef.current.sx,
 						y: dragRef.current.spy + ev.clientY - dragRef.current.sy
 					});
 				};
-				const onUp = () => {
+				const stopDrag = () => {
 					dragRef.current.active = false;
 					document.removeEventListener("mousemove", onMove);
-					document.removeEventListener("mouseup", onUp);
+					document.removeEventListener("mouseup", stopDrag);
+					dragStopRef.current = null;
 				};
+				dragStopRef.current = stopDrag;
 				document.addEventListener("mousemove", onMove);
-				document.addEventListener("mouseup", onUp);
+				document.addEventListener("mouseup", stopDrag);
 			}, [pos]);
+			(0, react.useEffect)(() => () => {
+				dragStopRef.current?.();
+			}, []);
 			const onWheelCb = (0, react.useCallback)((e) => {
 				e.preventDefault();
+				movedRef.current = false;
 				const el = containerRef.current;
 				if (!el) return;
 				const rect = el.getBoundingClientRect();
 				const mx = rect.width / 2, my = rect.height / 2;
 				const factor = e.deltaY > 0 ? .97 : 1.03;
-				const nz = clampZoom(zoom * factor);
-				const nx = mx - (mx - pos.x) * (nz / zoom);
-				const ny = my - (my - pos.y) * (nz / zoom);
+				const { zoom: z, pos: p } = viewRef.current;
+				const nz = clampZoom(z * factor);
+				const nx = mx - (mx - p.x) * (nz / z);
+				const ny = my - (my - p.y) * (nz / z);
 				setZoom(nz);
 				setPos({
 					x: nx,
 					y: ny
 				});
-			}, [zoom, pos]);
-			(0, react.useEffect)(() => {
-				const el = containerRef.current;
-				if (!el) return;
-				el.addEventListener("wheel", onWheelCb, { passive: false });
-				return () => el.removeEventListener("wheel", onWheelCb);
-			}, [onWheelCb]);
+			}, []);
 			const onTouchStartCb = (0, react.useCallback)((e) => {
-				const el = containerRef.current;
-				if (!el) return;
-				if (e.touches.length === 1) {
-					pinchRef.current = null;
-					const tp = e.touches[0];
-					touchDragRef.current = {
-						sx: tp.clientX,
-						sy: tp.clientY,
-						spx: viewRef.current.pos.x,
-						spy: viewRef.current.pos.y
-					};
-					return;
-				}
+				const card = containerRef.current;
+				if (!card) return;
+				movedRef.current = false;
 				if (e.touches.length >= 2) {
 					touchDragRef.current = null;
-					const rect = el.getBoundingClientRect();
+					const rect = card.getBoundingClientRect();
 					const a = e.touches[0], b = e.touches[1];
 					pinchRef.current = {
 						dist: Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY),
@@ -6000,16 +6296,32 @@ window.__ModuleLoader__.load({
 						px: viewRef.current.pos.x,
 						py: viewRef.current.pos.y
 					};
+					return;
+				}
+				if (e.touches.length === 1) {
+					pinchRef.current = null;
+					if (!card.contains(e.target)) {
+						touchDragRef.current = null;
+						return;
+					}
+					const tp = e.touches[0];
+					touchDragRef.current = {
+						sx: tp.clientX,
+						sy: tp.clientY,
+						spx: viewRef.current.pos.x,
+						spy: viewRef.current.pos.y
+					};
 				}
 			}, []);
 			const onTouchMoveCb = (0, react.useCallback)((e) => {
-				const el = containerRef.current;
-				if (!el) return;
+				const card = containerRef.current;
+				if (!card) return;
 				if (e.touches.length >= 2 && pinchRef.current !== null) {
 					e.preventDefault();
+					movedRef.current = true;
 					const p = pinchRef.current;
 					if (p.dist <= 0) return;
-					const rect = el.getBoundingClientRect();
+					const rect = card.getBoundingClientRect();
 					const a = e.touches[0], b = e.touches[1];
 					const dist = Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY);
 					const cx = (a.clientX + b.clientX) / 2 - rect.left;
@@ -6026,6 +6338,7 @@ window.__ModuleLoader__.load({
 					e.preventDefault();
 					const d = touchDragRef.current;
 					const tp = e.touches[0];
+					if (Math.abs(tp.clientX - d.sx) > 4 || Math.abs(tp.clientY - d.sy) > 4) movedRef.current = true;
 					setPos({
 						x: d.spx + tp.clientX - d.sx,
 						y: d.spy + tp.clientY - d.sy
@@ -6048,19 +6361,29 @@ window.__ModuleLoader__.load({
 				}
 			}, []);
 			(0, react.useEffect)(() => {
-				const el = containerRef.current;
-				if (!el) return;
-				el.addEventListener("touchstart", onTouchStartCb, { passive: false });
-				el.addEventListener("touchmove", onTouchMoveCb, { passive: false });
-				el.addEventListener("touchend", onTouchEndCb, { passive: false });
-				el.addEventListener("touchcancel", onTouchEndCb, { passive: false });
+				if (!overlayEl) return;
+				const noPageGesture = (e) => e.preventDefault();
+				overlayEl.addEventListener("wheel", onWheelCb, { passive: false });
+				overlayEl.addEventListener("touchstart", onTouchStartCb, { passive: false });
+				overlayEl.addEventListener("touchmove", onTouchMoveCb, { passive: false });
+				overlayEl.addEventListener("touchend", onTouchEndCb, { passive: false });
+				overlayEl.addEventListener("touchcancel", onTouchEndCb, { passive: false });
+				overlayEl.addEventListener("gesturestart", noPageGesture, { passive: false });
+				overlayEl.addEventListener("gesturechange", noPageGesture, { passive: false });
+				overlayEl.addEventListener("gestureend", noPageGesture, { passive: false });
 				return () => {
-					el.removeEventListener("touchstart", onTouchStartCb);
-					el.removeEventListener("touchmove", onTouchMoveCb);
-					el.removeEventListener("touchend", onTouchEndCb);
-					el.removeEventListener("touchcancel", onTouchEndCb);
+					overlayEl.removeEventListener("wheel", onWheelCb);
+					overlayEl.removeEventListener("touchstart", onTouchStartCb);
+					overlayEl.removeEventListener("touchmove", onTouchMoveCb);
+					overlayEl.removeEventListener("touchend", onTouchEndCb);
+					overlayEl.removeEventListener("touchcancel", onTouchEndCb);
+					overlayEl.removeEventListener("gesturestart", noPageGesture);
+					overlayEl.removeEventListener("gesturechange", noPageGesture);
+					overlayEl.removeEventListener("gestureend", noPageGesture);
 				};
 			}, [
+				overlayEl,
+				onWheelCb,
 				onTouchStartCb,
 				onTouchMoveCb,
 				onTouchEndCb
@@ -6078,10 +6401,22 @@ window.__ModuleLoader__.load({
 				imgSize
 			]);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Portal, { children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				ref: setOverlayEl,
 				className: "dab-overlay",
+				style: {
+					touchAction: "none",
+					overscrollBehavior: "contain"
+				},
 				onClick: (e) => {
+					if (movedRef.current) {
+						movedRef.current = false;
+						return;
+					}
 					if (e.target === e.currentTarget) onClose();
 				},
+				onMouseDown: () => {
+					movedRef.current = false;
+				},
 				children: [
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 						className: "dab-overlay-title",
@@ -6177,7 +6512,7 @@ window.__ModuleLoader__.load({
 				labelKey: "bgModeCenter"
 			}
 		];
-		function BackgroundPage({ p }) {
+		function BackgroundPage({ p, notify }) {
 			const { t, setWpFromServer, setVideo, setWop, setBl, setBgType, setGeneratedBg, regenerateBg, setRegenerateOnReload, setRotation, addRotationItems, removeRotationItem, rotateNow, setVideoFromUrl, useStore } = p;
 			const storeUrl = useStore((s) => s.url);
 			const backgroundType = useStore((s) => s.backgroundType);
@@ -6194,7 +6529,11 @@ window.__ModuleLoader__.load({
 			const [urlVal, setUrlVal] = (0, react.useState)("");
 			const [urlBusy, setUrlBusy] = (0, react.useState)(false);
 			const [urlErr, setUrlErr] = (0, react.useState)(null);
+			const bgRev = useStore((s) => s.bgRev);
 			const [mode, setModeState] = (0, react.useState)(rBgMode());
+			(0, react.useEffect)(() => {
+				setModeState(rBgMode());
+			}, [bgRev]);
 			const isVideo = backgroundType === "video";
 			const isStatic = backgroundType === "image" || isVideo;
 			const isGenerated = !isStatic;
@@ -6208,14 +6547,15 @@ window.__ModuleLoader__.load({
 				genPreset,
 				generatedBg?.seed
 			]);
-			const onFileSelect = (f) => {
+			const onFileSelect = async (f) => {
 				if (f.type.startsWith("video/")) {
-					setVideo(f, f.type);
+					const outcome = await setVideo(f, f.type);
+					if (!outcome.ok) notify(uploadRefusalText(outcome, t, "videoUploadFail"), false);
 					return;
 				}
-				uploadWallpaper(f).then((ok) => {
-					if (ok) setWpFromServer(WALLPAPER_SERVE_URL);
-				});
+				const outcome = await uploadWallpaper(f);
+				if (outcome.ok) setWpFromServer(WALLPAPER_SERVE_URL);
+				else notify(uploadRefusalText(outcome, t, "bgUploadFail"), false);
 			};
 			const onDrop = (e) => {
 				e.preventDefault();
@@ -7489,31 +7829,37 @@ window.__ModuleLoader__.load({
 		//#endregion
 		//#region src/client/components/ThemeSection.tsx
 		/**
-		* dsh-any-background — settings section shell.
+		* dsh-any-background — appearance shell for the five pages.
 		*
-		* The host renders this section only while the settings dialog is open and the
-		* section is the active nav entry, so mounting IS being visible. The section is
-		* rendered INLINE inside the host settings dialog's content column (the host
-		* provides the modal chrome); the shell is a left nav rail + page body. Only
-		* the transient toast escapes through a Portal (the shell's container-type
-		* containment would otherwise capture its fixed positioning).
+		* Two surfaces render this shell, and only the chrome differs:
+		*   · `settings` — injected into the host settings dialog's content column,
+		*     which supplies the modal frame (nav rail on the left, brand block, page
+		*     max-width, the dialog's own scrolling);
+		*   · `sidebar`  — a page inside dsh-better-sidebar, where the panel is much
+		*     narrower, is handed a full-height column, and has to own its own scroll
+		*     region. The brand block is dropped (the sidebar's tab bar already names
+		*     the page) and the rail turns into a compact row.
+		* The five pages themselves never branch on the surface: width-driven
+		* adaptation lives in the stylesheet's container queries, which measure the
+		* shell itself rather than assuming either surface's width.
 		*/
 		function ThemeSection(props) {
 			ensureUiCss();
 			const { t } = props;
+			const surface = props.surface ?? "settings";
 			const [page, setPage] = (0, react.useState)(0);
 			const [toast, setToast] = (0, react.useState)(null);
 			const toastTimer = (0, react.useRef)(void 0);
 			(0, react.useEffect)(() => () => window.clearTimeout(toastTimer.current), []);
-			const notify = (msg, ok = true) => {
+			const notify = (0, react.useCallback)((msg, ok = true) => {
 				setToast({
 					msg,
 					ok
 				});
 				window.clearTimeout(toastTimer.current);
 				toastTimer.current = window.setTimeout(() => setToast(null), 2600);
-			};
-			const pages = [
+			}, []);
+			const pages = (0, react.useMemo)(() => [
 				{
 					label: t("pageColor"),
 					Icon: DropletIcon,
@@ -7538,7 +7884,10 @@ window.__ModuleLoader__.load({
 				{
 					label: t("pageBackground"),
 					Icon: PhotoIcon,
-					node: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(BackgroundPage, { p: props })
+					node: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(BackgroundPage, {
+						p: props,
+						notify
+					})
 				},
 				{
 					label: t("pageProfile"),
@@ -7548,16 +7897,21 @@ window.__ModuleLoader__.load({
 						notify
 					})
 				}
-			];
+			], [
+				t,
+				props,
+				notify
+			]);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(ErrorBoundary, {
 				t,
 				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 					className: "dab-root",
+					"data-dab-surface": surface,
 					children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: "dab-shell",
 						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("nav", {
 							className: "dab-nav",
-							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							children: [surface === "sidebar" ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 								className: "dab-brand",
 								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 									className: "dab-brand-tile",
@@ -7597,6 +7951,138 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
+		//#region src/client/sidebar/store-hook.ts
+		/**
+		* dsh-any-background — selector hook over a host store instance.
+		*
+		* The settings slot kit hands the pages a `useStore(selector)` hook that is
+		* bound to this plugin's store instance by the host renderer. A better-sidebar
+		* page gets no such kit — its tab props carry `ctx`/`store`/`scope` for
+		* better-sidebar's own store — so the same contract is rebuilt here from the
+		* store instance itself, which already IS an observable source
+		* (`getSnapshot`/`subscribe`, see `defineStore` in the host's client store).
+		*
+		* Semantics match the host binding on purpose: reduce the published snapshot
+		* through the selector and compare with `Object.is`, so a page subscribing to
+		* one field does not re-render on unrelated writes.
+		*/
+		/**
+		* Bind a store instance to a `useStore(selector)` hook. Call once per store and
+		* share the result: the returned hook keeps one subscription identity for its
+		* whole lifetime.
+		* @param store - observable store instance (`defineStore` handle).
+		* @returns a selector hook reading that instance.
+		*/
+		function createStoreHook(store) {
+			const subscribe = (onChange) => store.subscribe(onChange);
+			const { getSnapshot } = store;
+			return function useStoreSelector(selector) {
+				const cache = (0, react.useRef)(null);
+				const read = (0, react.useCallback)(() => {
+					const snapshot = getSnapshot();
+					const hit = cache.current;
+					if (hit !== null && hit.snapshot === snapshot) return hit.value;
+					const value = selector(snapshot);
+					cache.current = {
+						snapshot,
+						value
+					};
+					return value;
+				}, [selector]);
+				return (0, react.useSyncExternalStore)(subscribe, read, read);
+			};
+		}
+		//#endregion
+		//#region src/client/sidebar/tab.tsx
+		/**
+		* dsh-any-background — dsh-better-sidebar integration.
+		*
+		* Publishes the plugin's appearance controls as a sidebar page ("主题") in
+		* better-sidebar's tab registry. The page renders the SAME five-page tree as
+		* the settings section — `ThemeSection` takes a `surface` variant — so there is
+		* one UI to maintain, not two forks of it.
+		*
+		* The dependency is optional at every level, which is why nothing here imports
+		* the package:
+		*   · the service is read off the client context at runtime, so a DSH install
+		*     without better-sidebar silently registers nothing, and a better-sidebar
+		*     that mounts *after* this plugin still gets the page (`ctx.inject` fires
+		*     whenever the service shows up, never when it never does);
+		*   · the plugin's own types are restated in the minimal local contract below
+		*     instead of imported — a value import would be rejected by the host's
+		*     client-bundle purity gate, and even a type-only import would make the
+		*     package a build-time dependency for everyone who does not run it.
+		*/
+		/**
+		* The active locale id, used as a re-render signal: page labels are resolved by
+		* calling `t(...)` at render time, so the props object (and with it the memoized
+		* page tree) has to be rebuilt when the language flips — otherwise the page
+		* would keep painting the previous language until some unrelated store write
+		* happened to re-render it.
+		* @param locale - host locale service.
+		* @returns the active locale id (a stable string, safe for `Object.is`).
+		*/
+		function useActiveLocale(locale) {
+			const subscribe = (0, react.useCallback)((onChange) => locale.subscribe(onChange), [locale]);
+			const read = (0, react.useCallback)(() => locale.getSnapshot().active, [locale]);
+			return (0, react.useSyncExternalStore)(subscribe, read, read);
+		}
+		function ThemeTab({ face, useStore, locale }) {
+			const active = useActiveLocale(locale);
+			const props = (0, react.useMemo)(() => ({
+				...face,
+				useStore
+			}), [
+				face,
+				useStore,
+				active
+			]);
+			return (0, react.createElement)(ThemeSection, {
+				...props,
+				surface: "sidebar"
+			});
+		}
+		/**
+		* Register the appearance page with better-sidebar, if it is installed.
+		*
+		* Call from the client `apply`. The registration is owned by the injected
+		* scope's effect, so unloading the plugin (or HMR) withdraws it — without that,
+		* the next activation would throw on the duplicate id.
+		* @param ctx - client context.
+		* @param opts.face - lazy accessor for the shared business face.
+		* @param opts.store - the plugin's store instance, or null on a host where the
+		*   store module never resolved (in that case there is nothing to bind and no
+		*   page is registered).
+		*/
+		function registerThemeSidebarTab(ctx, opts) {
+			const { store } = opts;
+			if (store === null || typeof store.getSnapshot !== "function" || typeof store.subscribe !== "function") {
+				console.warn("dsh-any-background: no observable store instance on this host; the sidebar page stays unregistered");
+				return;
+			}
+			const locale = ctx.locale;
+			const t = locale.bind(NS);
+			const useStore = createStoreHook(store);
+			const ORDER = 55;
+			ctx.inject?.(["betterSidebar"], (scope) => {
+				const service = scope.betterSidebar;
+				if (service === void 0) return;
+				const face = opts.face();
+				scope.effect(() => service.registerTab({
+					id: "dsh-any-background:theme",
+					title: () => t("nav"),
+					icon: (size) => (0, react.createElement)(SunIcon, { size }),
+					order: ORDER,
+					single: true,
+					component: () => (0, react.createElement)(ThemeTab, {
+						face,
+						useStore,
+						locale
+					})
+				}));
+			});
+		}
+		//#endregion
 		//#region src/client/index.tsx
 		/**
 		* dsh-any-background — browser half entry.
@@ -7617,6 +8103,7 @@ window.__ModuleLoader__.load({
 			initRpc((endpoint, payload) => ctx.connection.rpc.call(RPC_CHANNEL, endpoint, payload).then((res) => res));
 			const [initH, initS, initL] = rColor();
 			let customDispose = null;
+			let registerFailed = false;
 			const registerCustom = (h, s, l) => {
 				customDispose?.();
 				try {
@@ -7649,23 +8136,47 @@ window.__ModuleLoader__.load({
 						colorScheme,
 						tokens
 					});
-				} catch {
+				} catch (e) {
+					if (!(() => {
+						try {
+							return ctx.theme.getTheme().themes.some((t) => t.id === CUSTOM_ID);
+						} catch {
+							return false;
+						}
+					})()) {
+						if (!registerFailed) {
+							registerFailed = true;
+							console.error("dsh-any-background: host theme register failed; the custom skin will stay inactive", e);
+						}
+						customDispose = null;
+						return false;
+					}
 					customDispose = null;
 				}
-				const present = ctx.theme.getTheme().themes.some((t) => t.id === CUSTOM_ID);
+				const present = (() => {
+					try {
+						return ctx.theme.getTheme().themes.some((t) => t.id === CUSTOM_ID);
+					} catch {
+						return false;
+					}
+				})();
 				if (present) ctx.theme.setTheme(CUSTOM_ID);
 				return present;
 			};
 			if (rHasColor()) registerCustom(initH, initS, initL);
-			onVerdictApplied(() => {
+			const disposeVerdict = onVerdictApplied(() => {
 				if (!rHasColor()) registerCustom();
 			});
-			onColorAdopted((hsl) => {
+			const disposeColorAdopted = onColorAdopted((hsl) => {
 				registerCustom(hsl[0], hsl[1], hsl[2]);
 				saveConfig();
 				colorRev++;
 				bound?.syncColor(hslToHsv(hsl[0], hsl[1], hsl[2]), colorRev);
 			});
+			ctx.effect(() => () => {
+				disposeVerdict();
+				disposeColorAdopted();
+			}, "dsh-any-background: verdict/color listeners");
 			ctx.effect(() => () => {
 				customDispose?.();
 				if (colorTimerRef.current !== null) window.clearTimeout(colorTimerRef.current);
@@ -7683,7 +8194,7 @@ window.__ModuleLoader__.load({
 			let colorRev = 0;
 			let bgRev = 0;
 			const colorTimerRef = { current: null };
-			const store = defineStore({
+			const storeSpec = defineStore === null ? null : defineStore({
 				init: () => ({
 					url: null,
 					rev: -1,
@@ -7734,13 +8245,44 @@ window.__ModuleLoader__.load({
 					}
 				}
 			});
+			/** One shared instance, whatever the host build handed back.
+			*
+			*  The plugin publishes a single appearance state that BOTH surfaces read —
+			*  the settings section (through the renderer's `useStore`) and the
+			*  better-sidebar page (through the hook in `sidebar/store-hook`). Handing the
+			*  host a declaration whose `create` always returns this very instance is what
+			*  keeps them from drifting: letting the renderer mint its own would give the
+			*  sidebar a second, permanently empty copy of the state. */
+			const storeInstance = storeSpec === null ? null : typeof storeSpec.getSnapshot === "function" ? storeSpec : storeSpec.create();
+			/** What gets registered: the instance on newer builds, a single-instance
+			*  declaration on the ones that expect a declaration. */
+			const store = storeSpec === null || storeInstance === storeSpec ? storeSpec : {
+				spec: storeSpec.spec ?? {},
+				create: () => storeInstance
+			};
 			let bound = null;
+			if (storeInstance !== null) bound = storeInstance.actions;
 			const syncBg = () => {
 				rev++;
 				bgRev++;
 				bound?.syncBg(rWp(), rev, cfg.backgroundType, cfg.generatedBg, bgRev, cfg.regenerateOnReload);
 			};
-			onGeneratedSnapshot(syncBg);
+			const disposeSnapshot = onGeneratedSnapshot(syncBg);
+			ctx.effect(() => () => disposeSnapshot(), "dsh-any-background: snapshot listener");
+			/** Capture the first frame of the video now applied and finish its
+			*  adaptation: the frame stands in for every still-image API (previews,
+			*  color extraction) and the brightness verdict follows it. The stale guard
+			*  skips a capture whose video was swapped out from under it (another
+			*  upload or a rotation switch landing mid-decode). */
+			const captureAndApplyVideo = (url) => {
+				if (url === null) return;
+				captureVideoSnapshot(url).then((snap) => {
+					if (rWpVideo() !== url) return;
+					setWpVideoSnapshot(snap);
+					applyThemeColor();
+					syncBg();
+				});
+			};
 			let metaRev = 0;
 			const syncMetaNow = () => {
 				metaRev++;
@@ -7861,7 +8403,7 @@ window.__ModuleLoader__.load({
 			const scheduleTick = () => {
 				const sc = rSchedule();
 				if (!sc.enabled) return;
-				const want = (sc.mode === "system" ? window.matchMedia?.("(prefers-color-scheme: dark)").matches ?? false : isNightNow(sc)) ? sc.nightProfile : sc.dayProfile;
+				const want = (sc.mode === "system" ? window.matchMedia?.("(prefers-color-scheme: dark)")?.matches ?? false : isNightNow(sc)) ? sc.nightProfile : sc.dayProfile;
 				if (!want || want === cfg.activeProfile) return;
 				applyProfileById(want);
 			};
@@ -7889,12 +8431,7 @@ window.__ModuleLoader__.load({
 				if (cfg.backgroundType === "video") {
 					const v = rWpVideo();
 					if (v) {
-						captureVideoSnapshot(v).then((snap) => {
-							if (rWpVideo() !== v) return;
-							setWpVideoSnapshot(snap);
-							applyThemeColor();
-							syncBg();
-						});
+						captureAndApplyVideo(v);
 						applyWp();
 					} else {
 						cfg.backgroundType = "image";
@@ -7944,19 +8481,25 @@ window.__ModuleLoader__.load({
 			document.body.append(sentinel);
 			const viewportObserver = new ResizeObserver(applySoon);
 			viewportObserver.observe(sentinel);
-			const dprQuery = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
-			dprQuery.addEventListener("change", applySoon);
+			const dprQuery = window.matchMedia?.(`(resolution: ${window.devicePixelRatio}dppx)`);
+			dprQuery?.addEventListener?.("change", applySoon);
 			ctx.effect(() => () => {
 				viewportObserver.disconnect();
-				dprQuery.removeEventListener("change", applySoon);
+				dprQuery?.removeEventListener?.("change", applySoon);
 				sentinel.remove();
 			}, "dsh-any-background: viewport watch");
 			ctx.effect(() => ctx.locale.register(NS, {
 				zh,
 				en
 			}), "dsh-any-background: i18n");
-			const sectionInject = (actions) => {
-				bound = actions;
+			/** The business face, built once on first use and shared by both surfaces
+			*  (the settings section and the better-sidebar page). Memoizing is not just
+			*  about cost: the face closes over per-surface state — the font preview blob
+			*  URL behind releaseFontPreview — so a second build would give the sidebar
+			*  its own preview slot and leak whichever copy never gets released. */
+			let themeFace = null;
+			const buildFace = () => {
+				if (themeFace !== null) return themeFace;
 				syncBg();
 				syncMetaNow();
 				const playVideoFromBlob = (blob, mime) => {
@@ -7967,15 +8510,10 @@ window.__ModuleLoader__.load({
 					setWpVideoUrl(localUrl, mime ?? blob.type ?? "video/mp4");
 					applyWp();
 					syncBg();
-					const applied = rWpVideo();
-					captureVideoSnapshot(localUrl).then((snap) => {
-						if (rWpVideo() !== applied) return;
-						setWpVideoSnapshot(snap);
-						applyThemeColor();
-						syncBg();
-					});
-					uploadVideo(blob, mime ?? blob.type ?? "video/mp4").then((ok) => {
-						if (ok) persistConfig();
+					captureAndApplyVideo(rWpVideo());
+					return uploadVideo(blob, mime ?? blob.type ?? "video/mp4").then((outcome) => {
+						if (outcome.ok) persistConfig();
+						return outcome;
 					});
 				};
 				const FONT_EXT_MIME = {
@@ -8002,7 +8540,7 @@ window.__ModuleLoader__.load({
 				};
 				const [wh, ws, wl] = rColor();
 				const [dh, ds, dv] = hslToHsv(wh, ws, wl);
-				return {
+				const built = {
 					t: ctx.locale.bind(NS),
 					hue: dh,
 					sat: ds,
@@ -8052,13 +8590,11 @@ window.__ModuleLoader__.load({
 							applyThemeColor();
 							syncBg();
 							saveConfig();
-							return;
-						}
-						if (typeof u !== "string") {
-							playVideoFromBlob(u, mime);
-							return;
+							return { ok: true };
 						}
-						const live = await persistVideo(u) ? VIDEO_SERVE_URL : u;
+						if (typeof u !== "string") return playVideoFromBlob(u, mime);
+						const ok = await persistVideo(u);
+						const live = ok ? VIDEO_SERVE_URL : u;
 						cfg.backgroundType = "video";
 						setWpUrl(null);
 						cfg.videoBgState = { ...DEFAULT_CONFIG.bgState };
@@ -8066,13 +8602,8 @@ window.__ModuleLoader__.load({
 						applyWp();
 						saveConfig();
 						syncBg();
-						const applied = rWpVideo();
-						captureVideoSnapshot(live).then((snap) => {
-							if (rWpVideo() !== applied) return;
-							setWpVideoSnapshot(snap);
-							applyThemeColor();
-							syncBg();
-						});
+						captureAndApplyVideo(rWpVideo());
+						return { ok };
 					},
 					setBgType: (type) => {
 						setBackgroundType(type);
@@ -8116,18 +8647,21 @@ window.__ModuleLoader__.load({
 						const localUrl = URL.createObjectURL(file);
 						fontPreviewUrl = localUrl;
 						applyFontFace(localUrl, true, fontMimeFromName(file.name));
-						const mime = await uploadFont(file);
-						if (mime === null) {
+						const outcome = await uploadFont(file);
+						if (!outcome.ok || outcome.mime === void 0) {
 							applyStoredFont();
 							releaseFontPreview(4e3);
-							return false;
+							return {
+								ok: false,
+								refusal: outcome.refusal
+							};
 						}
-						cfg.fontMime = mime;
+						cfg.fontMime = outcome.mime;
 						cfg.fontEnabled = true;
-						applyFontFace(FONT_SERVE_URL, true, mime);
+						applyFontFace(FONT_SERVE_URL, true, outcome.mime);
 						releaseFontPreview(4e3);
 						persistConfig();
-						return true;
+						return { ok: true };
 					},
 					removeFont: () => {
 						releaseFontPreview(0);
@@ -8213,7 +8747,7 @@ window.__ModuleLoader__.load({
 						a.href = url;
 						a.download = "dsh-any-theme.json";
 						a.click();
-						URL.revokeObjectURL(url);
+						window.setTimeout(() => URL.revokeObjectURL(url), 4e3);
 					},
 					importTheme: async (file) => {
 						try {
@@ -8233,16 +8767,9 @@ window.__ModuleLoader__.load({
 									}
 									if (blob !== null) playVideoFromBlob(blob, cfg.videoMime);
 									else {
-										const live = await persistVideo(video) ? VIDEO_SERVE_URL : video;
-										setWpVideoUrl(live, cfg.videoMime);
+										setWpVideoUrl(await persistVideo(video) ? VIDEO_SERVE_URL : video, cfg.videoMime);
 										applyWp();
-										const applied = rWpVideo();
-										captureVideoSnapshot(live).then((snap) => {
-											if (rWpVideo() !== applied) return;
-											setWpVideoSnapshot(snap);
-											applyThemeColor();
-											syncBg();
-										});
+										captureAndApplyVideo(rWpVideo());
 									}
 								} else {
 									setWpVideoUrl(null, null);
@@ -8401,18 +8928,19 @@ window.__ModuleLoader__.load({
 						applyWp();
 						saveConfig();
 						syncBg();
-						const applied = rWpVideo();
-						captureVideoSnapshot(applied).then((snap) => {
-							if (rWpVideo() !== applied) return;
-							setWpVideoSnapshot(snap);
-							applyThemeColor();
-							syncBg();
-						});
+						captureAndApplyVideo(rWpVideo());
 						return true;
 					}
 				};
+				themeFace = built;
+				return built;
 			};
-			ctx.slots.inject("settings.section", () => ctx.slots.register({
+			const sectionInject = (actions) => {
+				bound = actions;
+				return buildFace();
+			};
+			if (store === null) console.error("dsh-any-background: settings panel disabled on this host (no store module)");
+			else ctx.slots.inject("settings.section", () => ctx.slots.register({
 				name: "settings.section",
 				id: "dsh-any-background",
 				order: 35,
@@ -8421,6 +8949,10 @@ window.__ModuleLoader__.load({
 				store,
 				inject: sectionInject
 			}, ThemeSection));
+			registerThemeSidebarTab(ctx, {
+				face: buildFace,
+				store: storeInstance
+			});
 			const navLabel = () => ctx.locale.bind(NS)("nav");
 			const applyNavIcon = () => {
 				const nav = document.querySelector("[role=\"dialog\"][aria-modal=\"true\"][aria-labelledby]")?.querySelector("nav");