dsh-background-by-model 0.7.2 → 0.7.3

package/lib/client.js

@@ -26,7 +26,7 @@ window.__ModuleLoader__.load({
 			pageProfile: "配置",
 			descInterface: "为主界面的各个区域单独调节透明度与模糊，营造空间层次感。这里的设置对所有模型生效",
 			descModelBg: "每条规则 = 一个匹配串 + 一组背景图与外观。切换模型时，从上往下找第一条匹配串出现在模型名里的规则；都没中就使用第 1 条。一条规则可以放多张图，按你设的节奏轮换",
-			descProfile: "把当前全部规则连同图片导出备份，或从文件一键恢复",
+			descProfile: "调整壁纸切换效果，并把当前全部规则连同图片导出备份，或从文件一键恢复",
 			uiTitle: "主界面",
 			uiOpacity: "透明度",
 			uiBlur: "模糊度",
@@ -142,7 +142,22 @@ window.__ModuleLoader__.load({
 			importFail: "导入失败，文件格式不正确",
 			footerTag: "按模型换背景插件",
 			holidayTitle: "节日特殊背景",
-			holidayEnable: "启用节日特殊背景（中秋当天、国庆 10 月 1–7 日）"
+			holidayEnable: "启用节日特殊背景（中秋当天、国庆 10 月 1–7 日）",
+			trTitle: "切换效果",
+			trEffect: "切换方式",
+			trEffectFade: "淡入淡出",
+			trEffectNone: "直接切换",
+			trEffectZoom: "缩放淡入",
+			trEffectSlide: "平移推入",
+			trEasing: "缓动",
+			trEasingEase: "标准",
+			trEasingLinear: "匀速",
+			trEasingOut: "先快后慢",
+			trEasingInOut: "两端慢",
+			trDuration: "切换时长",
+			trPreview: "试放",
+			trHint: "效果对所有换图生效：切模型、轮换、手动下一张、节日。「直接切换」和 0 秒一样是硬切",
+			trReducedHint: "系统开启了「减少动态效果」，实际切换不会播放动画"
 		};
 		const en = {
 			nav: "Model background",
@@ -152,7 +167,7 @@ window.__ModuleLoader__.load({
 			pageProfile: "Profile",
 			descInterface: "Tune opacity and blur per surface to build depth. These settings are global and apply to every model",
 			descModelBg: "Each rule is a match string plus a set of wallpapers and one look. On a model switch the list is scanned top-down for the first match string contained in the model name; if nothing hits, rule 1 is used. A rule can hold several images and rotate through them on a rhythm you set",
-			descProfile: "Back up every rule together with its image, or restore one from a file",
+			descProfile: "Tune how the wallpaper switches, and back up every rule together with its image — or restore one from a file",
 			uiTitle: "Interface",
 			uiOpacity: "Opacity",
 			uiBlur: "Blur",
@@ -268,9 +283,106 @@ window.__ModuleLoader__.load({
 			importFail: "Import failed — invalid file",
 			footerTag: "Per-model wallpaper plugin",
 			holidayTitle: "Holiday backgrounds",
-			holidayEnable: "Enable holiday backgrounds (Mid-Autumn day, Oct 1–7)"
+			holidayEnable: "Enable holiday backgrounds (Mid-Autumn day, Oct 1–7)",
+			trTitle: "Switch effect",
+			trEffect: "Transition",
+			trEffectFade: "Cross-fade",
+			trEffectNone: "Instant",
+			trEffectZoom: "Zoom in",
+			trEffectSlide: "Slide in",
+			trEasing: "Easing",
+			trEasingEase: "Standard",
+			trEasingLinear: "Linear",
+			trEasingOut: "Ease out",
+			trEasingInOut: "Ease in-out",
+			trDuration: "Duration",
+			trPreview: "Preview",
+			trHint: "The effect applies to every change: model switch, rotation, manual next, holidays. “Instant” and 0 s are the same hard cut",
+			trReducedHint: "Your system asks for reduced motion, so a real switch will not animate"
 		};
 		//#endregion
+		//#region src/client/transition.ts
+		/**
+		* Resolve the duration one switch uses, in ms (`0` = a hard cut).
+		*
+		*   1. `effect: 'none'` is a hard cut whatever the duration says — asking for no
+		*      animation and asking for 0 ms are the same request, and the effect is the
+		*      more explicit of the two;
+		*   2. otherwise the global `durationMs` decides, because a rule has no notion of
+		*      a transition and there is exactly one duration for every switch.
+		*
+		* A non-finite or negative value answers `0` (a hard cut) rather than a default:
+		* animating for an unknown length is the one answer that cannot be right. The
+		* input is already clamped by the shared sanitizer (`./schema`), so this is a
+		* guard against a hand-edited config, not a second clamp.
+		*/
+		function resolveFadeMs(transition) {
+			if (transition.effect === "none") return 0;
+			return Number.isFinite(transition.durationMs) && transition.durationMs > 0 ? transition.durationMs : 0;
+		}
+		/**
+		* The transform the incoming layer starts from, per effect.
+		*
+		* `zoom` starts ABOVE 1 and settles back to exactly `none`, never below or past
+		* it: the wallpaper would otherwise be left larger than the viewport, cropping a
+		* `fit` framing the user committed by hand. `slide` is a small push because a
+		* full-width travel of a full-bleed wallpaper reads as two wallpapers, not one
+		* transition.
+		*/
+		const START_TRANSFORM = {
+			fade: "none",
+			none: "none",
+			zoom: "scale(1.06)",
+			slide: "translateX(6%)"
+		};
+		/** The properties one effect actually animates — an unchanged property must not
+		*  be put on the transition list, or `fade` would stop being byte-for-byte the
+		*  cross-fade every release so far performed. */
+		function animatedProps(effect) {
+			return effect === "fade" ? ["opacity"] : ["opacity", "transform"];
+		}
+		/**
+		* Decide one switch: whether to animate, from what, to what, and on what curve.
+		*
+		* `canAnimate` is the caller's answer to "is there anything to animate from" —
+		* a first paint has no previous layer, and a wallpaper at 0% opacity is not on
+		* screen — plus the window-visibility question the caller already owns. It is
+		* passed in rather than computed here so this stays a pure function of its
+		* inputs.
+		*
+		* `reducedMotion` is honoured as a hard veto rather than a shortened duration:
+		* the point of the preference is that the interface stops moving, and a fast
+		* animation is still an animation.
+		*/
+		function transitionPlan(input) {
+			const still = {
+				opacity: "1",
+				transform: "none"
+			};
+			const moves = input.durationMs > 0;
+			if (!input.canAnimate || input.reducedMotion || input.effect === "none" || !moves) return {
+				animate: false,
+				durationMs: 0,
+				from: still,
+				to: still,
+				transition: "none",
+				willChange: ""
+			};
+			const props = animatedProps(input.effect);
+			const timing = `${input.durationMs}ms ${input.easing}`;
+			return {
+				animate: true,
+				durationMs: input.durationMs,
+				from: {
+					opacity: "0",
+					transform: START_TRANSFORM[input.effect]
+				},
+				to: still,
+				transition: props.map((p) => `${p} ${timing}`).join(", "),
+				willChange: props.join(", ")
+			};
+		}
+		//#endregion
 		//#region src/holiday.ts
 		const HOLIDAYS = [{
 			id: "mid-autumn",
@@ -449,15 +561,12 @@ window.__ModuleLoader__.load({
 		const ROTATE_MIN_MS = 5e3;
 		/** Slowest allowed dwell time (24 h): one image per day is still "rotation". */
 		const ROTATE_MAX_MS = 864e5;
-		/** Longest allowed cross-fade; 0 is a hard cut. */
-		const ROTATE_FADE_MAX_MS = 3e3;
 		/** Everything off: the shipped default, and what a config predating this feature gets. */
 		const DEFAULT_ROTATION = {
 			enabled: false,
 			intervalMs: 6e4,
 			order: "order",
-			advanceOnSwitch: false,
-			fadeMs: 320
+			advanceOnSwitch: false
 		};
 		/** A fresh rotation block (never hand out the shared default object). */
 		function defaultRotation() {
@@ -514,6 +623,32 @@ window.__ModuleLoader__.load({
 			rightbar: 0,
 			input: 0
 		};
+		/** Longest allowed switch duration; 0 is a hard cut. */
+		const TRANSITION_MAX_MS = 3e3;
+		/** Every accepted `effect`, in UI order. */
+		const TRANSITION_EFFECTS = [
+			"fade",
+			"none",
+			"zoom",
+			"slide"
+		];
+		/** Every accepted `easing`, in UI order. */
+		const TRANSITION_EASINGS = [
+			"ease",
+			"linear",
+			"ease-out",
+			"ease-in-out"
+		];
+		/** The shipped default: the cross-fade this plugin already performed, at 320 ms. */
+		const DEFAULT_TRANSITION = {
+			effect: "fade",
+			easing: "ease",
+			durationMs: 320
+		};
+		/** A fresh transition block (never hand out the shared default object). */
+		function defaultTransition() {
+			return { ...DEFAULT_TRANSITION };
+		}
 		/** Every slot a rule owns, in order. The one thing the render and store layers
 		*  ask of the image list, so a rule's slots are never enumerated ad hoc. */
 		function ruleSlots(rule) {
@@ -617,6 +752,7 @@ window.__ModuleLoader__.load({
 				rules: [],
 				opacities: { ...DEFAULT_PART_OPACITIES },
 				blurs: { ...DEFAULT_PART_BLURS },
+				transition: defaultTransition(),
 				settingsOpacity: 1,
 				chatTextOpacity: 0,
 				trajectoryOpacity: 1,
@@ -662,8 +798,7 @@ window.__ModuleLoader__.load({
 				enabled: r.enabled === true,
 				intervalMs: clamp$1(r.intervalMs, ROTATE_MIN_MS, ROTATE_MAX_MS, d.intervalMs),
 				order: ROTATE_ORDERS.includes(r.order) ? r.order : d.order,
-				advanceOnSwitch: r.advanceOnSwitch === true,
-				fadeMs: clamp$1(r.fadeMs, 0, ROTATE_FADE_MAX_MS, d.fadeMs)
+				advanceOnSwitch: r.advanceOnSwitch === true
 			};
 		}
 		/** Own-property test for values that may be anything at all (a raw JSON entry). */
@@ -671,6 +806,54 @@ window.__ModuleLoader__.load({
 			return Object.prototype.hasOwnProperty.call(o, key);
 		}
 		/**
+		* The duration a config written before the switch effect carries on any of its
+		* rules, or `undefined` when it carries none worth adopting.
+		*
+		* `rotate.fadeMs` was the per-rule duration from 0.7.0 on, and it had NO control
+		* anywhere — it could only be hand-edited, which is why the global setting
+		* replaced it. This is the one-shot lift that keeps such a hand-tuned value from
+		* being silently dropped on upgrade: the first rule whose value differs from the
+		* 320 ms every build shipped is adopted as the global duration. Values that are
+		* all the default are ignored, so an ordinary config keeps the ordinary default,
+		* and rules that DISAGREE cannot be represented by one global number — the first
+		* deliberate value wins, and the others are gone with the field they lived on.
+		*/
+		function legacyFadeMs(rawRules) {
+			if (!Array.isArray(rawRules)) return void 0;
+			for (const entry of rawRules) {
+				const rotate = entry?.rotate;
+				if (rotate === null || typeof rotate !== "object") continue;
+				const value = rotate.fadeMs;
+				if (typeof value !== "number" || !isFinite(value)) continue;
+				if (value === DEFAULT_TRANSITION.durationMs) continue;
+				return clamp$1(value, 0, TRANSITION_MAX_MS, DEFAULT_TRANSITION.durationMs);
+			}
+		}
+		/**
+		* Coerce one persisted transition block; a config written before this setting
+		* existed has no `transition` key at all and gets the shipped default, which is
+		* the behaviour it already had.
+		*
+		* `legacyMs` is the per-rule `fadeMs` this shape replaced (see `legacyFadeMs`),
+		* adopted only when the incoming config has no `durationMs` of its own — so a
+		* deliberate hand-tuned blend survives the upgrade instead of being dropped with
+		* the field it used to live on.
+		*
+		* `durationMs` is clamped with `0` kept as a real value (a hard cut) rather than
+		* read as "absent": 0 is exactly how a hard cut is asked for without changing
+		* the effect.
+		*/
+		function normalizeTransition(raw, legacyMs) {
+			const t = raw ?? {};
+			const d = DEFAULT_TRANSITION;
+			const fallback = typeof legacyMs === "number" && isFinite(legacyMs) ? legacyMs : d.durationMs;
+			return {
+				effect: TRANSITION_EFFECTS.includes(t.effect) ? t.effect : d.effect,
+				easing: TRANSITION_EASINGS.includes(t.easing) ? t.easing : d.easing,
+				durationMs: clamp$1(t.durationMs, 0, TRANSITION_MAX_MS, fallback)
+			};
+		}
+		/**
 		* Coerce one persisted image entry, or null when it lacks a usable slot.
 		*
 		* `inherit` is the RULE's own color, and it is applied only to an entry that has
@@ -807,6 +990,7 @@ window.__ModuleLoader__.load({
 				rules,
 				opacities,
 				blurs,
+				transition: normalizeTransition(r.transition, legacyFadeMs(r.rules)),
 				settingsOpacity: clamp01(r.settingsOpacity, 1),
 				chatTextOpacity: clamp01(r.chatTextOpacity, 0),
 				trajectoryOpacity: clamp01(r.trajectoryOpacity, 1),
@@ -1084,13 +1268,26 @@ window.__ModuleLoader__.load({
 		function rBgState() {
 			return activeImage()?.bgState ?? DEFAULT_BG_STATE;
 		}
-		/** Rotation of the active rule; the shipped default when nothing is active. */
-		function rRotation() {
-			return activeRule()?.rotate ?? defaultRotation();
+		/**
+		* The GLOBAL wallpaper-switch transition (effect, easing, duration).
+		*
+		* Read from the config on every apply rather than cached: the Config page edits
+		* it while a wallpaper is on screen, and the next switch has to use what the
+		* user just chose.
+		*/
+		function rTransition() {
+			return cfg.transition ?? DEFAULT_TRANSITION;
 		}
-		/** Cross-fade duration the active rule asks for, in ms (0 = hard cut). */
+		/**
+		* Duration the next switch runs for, in ms (`0` = a hard cut).
+		*
+		* The two rungs are `resolveFadeMs`'s business (./transition): the effect can
+		* veto the animation outright, and otherwise the global duration decides. It is
+		* deliberately NOT a per-rule value — a rule has no notion of a transition, and
+		* the per-rule field this replaced had no control anywhere to set it with.
+		*/
 		function rFadeMs() {
-			return rRotation().fadeMs;
+			return resolveFadeMs(rTransition());
 		}
 		/** Paintable URL of the active rule's CURRENT image, or null when it has none. */
 		function rWp() {
@@ -1313,7 +1510,7 @@ window.__ModuleLoader__.load({
 			const d = data;
 			const slots = Array.isArray(d.slots) ? d.slots.filter((s) => typeof s === "string") : [];
 			const schema = typeof d.schema === "number" && isFinite(d.schema) ? d.schema : null;
-			hostShape = schema === null ? "legacy" : schema >= 4 ? "current" : "legacy";
+			hostShape = schema === null ? "legacy" : schema >= 5 ? "current" : "legacy";
 			if (hostShape === "legacy") holdWrite();
 			return {
 				config: d.config,
@@ -1371,6 +1568,57 @@ window.__ModuleLoader__.load({
 			return parts.length > 0 ? parts.join(" ") : null;
 		}
 		//#endregion
+		//#region src/client/palette-fade.ts
+		/**
+		* Whether a palette change may interpolate at all.
+		*
+		* Only while the SCHEME stays put. A light↔dark flip is not a tint of the same
+		* palette, it is a different palette: interpolating between them walks the whole
+		* interface through mid-tones whose ink is wrong in both directions (dark text
+		* half-way into a dark palette), which looks worse than the switch it replaces.
+		* The wallpaper has no such problem — one image fades into another either way —
+		* so its own animation is deliberately untouched by this.
+		*
+		* `previous === null` means nothing has been painted yet (the first apply after a
+		* load): there is no colour to come from, so there is nothing to fade.
+		*/
+		function paletteFadeAllowed(previous, next) {
+			return previous === next;
+		}
+		/** One `@property` block per registered token. */
+		function registrations(names, initial) {
+			return names.map((n) => `@property ${n}{syntax:'<color>';inherits:true;initial-value:${initial[n]}}`).join("");
+		}
+		/**
+		* The stylesheet for one state: the registrations always, the transition only
+		* while a palette change is actually being painted.
+		*
+		* `durationMs = 0` deliberately emits NO transition rule. That is not only
+		* "instant": it is what keeps a slider drag instant, because the same call sites
+		* rewrite the `body{…}` rule on every frame of a drag and a live transition on
+		* those tokens would make the alphas lag behind the pointer.
+		*/
+		function paletteFadeCss(input) {
+			const names = Object.keys(input.initial).filter((n) => n.startsWith("--"));
+			if (names.length === 0) return "";
+			const css = registrations(names, input.initial);
+			if (!(input.durationMs > 0) || input.selectors.length === 0) return css;
+			const list = names.map((n) => `${n} ${input.durationMs}ms ${input.easing}`).join(",");
+			return `${css}${input.selectors.join(",")}{transition:${list}}`;
+		}
+		/**
+		* The same fade for an element the plugin paints INLINE (its columns and cards).
+		*
+		* No custom property is involved there — the element's own `background-color` is
+		* what changes — so the standard property is what has to be told. `0` means
+		* `none` rather than an empty value: an empty value would leave whatever the host
+		* had declared on that element, and the point of the 0 case is that a drag must
+		* not fade at all.
+		*/
+		function paletteFadeInline(durationMs, easing) {
+			return durationMs > 0 ? `background-color ${durationMs}ms ${easing}` : "none";
+		}
+		//#endregion
 		//#region src/client/utils/color.ts
 		function hsvToHsl(h, s, v) {
 			const l = v * (1 - s / 2);
@@ -1890,6 +2138,11 @@ window.__ModuleLoader__.load({
 
 /* ── profile page ────────────────────────────────────────────────────────── */
 .dab-profile-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(238px,1fr));gap:13px}
+/* The switch-effect preview: a two-tone swatch that replays the chosen effect in
+   the panel. It exists because a wallpaper fading into ITSELF is invisible —
+   the one thing a transition setting must not leave the user guessing about. */
+.dab-tr-preview{position:relative;overflow:hidden;flex:1;min-width:0;height:74px;border-radius:12px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2);background-image:linear-gradient(120deg,color-mix(in srgb,var(--dsw-alias-label-tertiary) 24%,transparent),transparent 70%)}
+.dab-tr-preview-in{position:absolute;inset:0;background-image:linear-gradient(120deg,var(--dsw-alias-brand-primary),color-mix(in srgb,var(--dsw-alias-brand-primary) 50%,var(--dsw-alias-bg-layer-1)))}
 .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}
@@ -2323,19 +2576,70 @@ window.__ModuleLoader__.load({
 		}
 		let pendingOps = null;
 		let tokensRaf = null;
+		/** When the pending frame was armed, so a frame that never ran can be spotted. */
+		let tokensArmedAt = 0;
+		/** A frame outstanding for longer than this is treated as lost (see below). */
+		const STALE_TOKENS_RAF_MS = 1e3;
+		/** The fingerprint of the palette + colour in force; see `applyCustomTokensNow`. */
+		function paletteKey(src, color) {
+			return src.own ? `own:${color[0]}|${color[1]}|${color[2]}` : `host:${HOST_SURFACE_TOKENS.map((n) => src.tokens[n] ?? "").join("|")}`;
+		}
+		/**
+		* Re-emit the interface palette, coalescing a slider drag into one frame.
+		*
+		* A PALETTE change is never coalesced, and that distinction is the whole point:
+		* this call is the only writer of the palette's INK. Every other surface has a
+		* second, synchronous writer (the dialog's layer tokens come from
+		* `applySettingsOverrides`, the columns' backgrounds from the view cards, the
+		* `--dsh-any-op-*` alphas from the same callback as the ink), so a palette update
+		* that is deferred and then lost leaves the surfaces on the NEW colour and the
+		* ink on the previous one — a dark palette with dark text, which reads as
+		* "the theme colour did nothing" and only a reload clears it.
+		*
+		* Measured in the field: a window that is not rendering can swallow the frame
+		* (the id stays armed, so every later update parks behind it), and a failure
+		* inside the write used to be swallowed by an empty `catch`. Both are handled
+		* here — a changed palette goes through synchronously, a stale frame is dropped
+		* instead of blocking forever, and the failure is logged (see `applyCustomTokensNow`).
+		*/
 		function applyCustomTokens(ops) {
 			pendingOps = ops;
-			if (tokensRaf !== null) return;
+			const src = palette();
+			if (src !== null && paletteKey(src, rColor()) !== baseTokenKey) {
+				flushTokens();
+				return lastFadeable;
+			}
+			if (tokensRaf !== null) {
+				if (Date.now() - tokensArmedAt <= STALE_TOKENS_RAF_MS) return false;
+				window.cancelAnimationFrame(tokensRaf);
+				tokensRaf = null;
+			}
+			tokensArmedAt = Date.now();
 			tokensRaf = requestAnimationFrame(() => {
 				tokensRaf = null;
-				if (pendingOps === null) return;
-				const o = pendingOps;
-				pendingOps = null;
-				applyCustomTokensNow(o);
+				flushTokens();
 			});
+			return false;
+		}
+		/** Run the pending token write now (one funnel, so no path can skip it). */
+		function flushTokens() {
+			if (pendingOps === null) return;
+			const o = pendingOps;
+			pendingOps = null;
+			applyCustomTokensNow(o);
 		}
 		let lastBgKey = "";
+		/**
+		* Whether the palette write in flight may fade — the answer `applyCustomTokens`
+		* hands back to the callers that paint their own surfaces inline.
+		*
+		* It has to travel out of `applyCustomTokensNow` (which is where the decision is
+		* made) because those callers run AFTER it in the same task, and re-deciding
+		* there would be a second opinion on the same question.
+		*/
+		let lastFadeable = false;
 		function applyCustomTokensNow(ops) {
+			lastFadeable = false;
 			const src = palette();
 			if (src === null) {
 				clearCustomTokens();
@@ -2347,8 +2651,18 @@ window.__ModuleLoader__.load({
 			const [h, s, l] = rColor();
 			try {
 				const forceDark = own && l < .55;
-				const key = own ? `own:${h}|${s}|${l}` : `host:${HOST_SURFACE_TOKENS.map((n) => tokens[n] ?? "").join("|")}`;
-				if (key !== baseTokenKey) {
+				const key = paletteKey(src, [
+					h,
+					s,
+					l
+				]);
+				const paletteChanged = key !== baseTokenKey;
+				const scheme = own ? forceDark ? "dark" : "light" : resolveHostDark() ? "dark" : "light";
+				const fadeable = paletteChanged && paletteFadeAllowed(paletteScheme, scheme);
+				lastFadeable = fadeable;
+				applyPaletteFade(fadeable);
+				if (paletteChanged) {
+					paletteScheme = scheme;
 					if (own) {
 						if (forceDark) document.body.setAttribute(DARK_ATTR, OWN_SCHEME);
 						else document.body.removeAttribute(DARK_ATTR);
@@ -2371,9 +2685,11 @@ window.__ModuleLoader__.load({
 				const bgKey = `${baseTokenKey}|${ops.bg}`;
 				if (bgKey !== lastBgKey) {
 					lastBgKey = bgKey;
-					applyPartOpacities(ops);
+					applyPartOpacities(ops, fadeable);
 				}
-			} catch {}
+			} catch (e) {
+				console.warn("dsh-background-by-model: could not re-emit the palette tokens", e);
+			}
 		}
 		const SETTINGS_PANEL_SEL = "[role=\"dialog\"][aria-modal=\"true\"][aria-labelledby]";
 		const SETTINGS_STYLE_RULE = `${SETTINGS_PANEL_SEL}{background:var(--dsh-any-bg-settings-surface,var(--dsw-alias-bg-layer-2));backdrop-filter:var(--dsh-any-blur-settings,none);}html[${THEMED_ATTR}] ${SETTINGS_PANEL_SEL}{--dsw-alias-bg-layer-1:var(--dsh-any-bg-settings-layer-1);--dsw-alias-bg-layer-2:var(--dsh-any-bg-settings-layer-2);--dsw-alias-bg-layer-3:var(--dsh-any-bg-settings-layer-3)}${SETTINGS_PANEL_SEL} .dab-card{backdrop-filter:var(--dsh-any-blur-card-panels,none);-webkit-backdrop-filter:var(--dsh-any-blur-card-panels,none)}`;
@@ -2408,6 +2724,100 @@ window.__ModuleLoader__.load({
 			write("--dsh-any-traj-layer-2", "--dsw-alias-bg-layer-2");
 			write("--dsh-any-traj-layer-3", "--dsw-alias-bg-layer-3");
 		}
+		/** Elements whose own token declarations change when the palette does: the body
+		*  (which everything else inherits), and the two surfaces that RE-declare the
+		*  layer tokens instead of inheriting them. */
+		const FADE_SELECTORS = [
+			"body",
+			SETTINGS_PANEL_SEL,
+			"[data-conversation-composer-overlay]"
+		];
+		/** The token names the plugin re-emits. One palette is enough: every branch
+		*  defines the same set, and an unknown name would only be registered when the
+		*  host can answer for it (see `fadeInitials`). */
+		function fadeTokenNames() {
+			return Object.keys(genTokens(220, .55, .25).tokens);
+		}
+		let fadeStyleEl = null;
+		let fadeInitials = null;
+		let fadeCssCache = "";
+		/** The scheme the last written palette had, so a FLIP can be told from a tint. */
+		let paletteScheme = null;
+		function ensureFadeSheet() {
+			if (fadeStyleEl?.isConnected) return fadeStyleEl;
+			fadeStyleEl = document.createElement("style");
+			fadeStyleEl.dataset.plugin = "dsh-background-by-model-fade";
+			markOwnSheet(fadeStyleEl);
+			document.head.appendChild(fadeStyleEl);
+			return fadeStyleEl;
+		}
+		/**
+		* The host's own value for each token — the `initial-value` a registration needs,
+		* and the test for whether a token may be registered at all.
+		*
+		* Read with the plugin's token sheet muted, for the same reason `readHostPalette`
+		* does it: our rule re-emits the very names being asked for. Cached, because the
+		* answer only changes with the host's scheme and a stale hint is only ever used
+		* for a token the host does not publish anyway.
+		*/
+		function fadeInitialsOf(names) {
+			if (fadeInitials !== null) return fadeInitials;
+			const sheet = tokenStyleEl;
+			const muted = sheet !== null && sheet.isConnected && !sheet.disabled;
+			if (muted) sheet.disabled = true;
+			try {
+				const computed = getComputedStyle(document.body);
+				const out = {};
+				for (const name of names) {
+					const used = resolveCssColor(computed.getPropertyValue(name));
+					if (used !== null) out[name] = used;
+				}
+				fadeInitials = out;
+				return out;
+			} catch {
+				fadeInitials = {};
+				return fadeInitials;
+			} finally {
+				if (muted) sheet.disabled = false;
+			}
+		}
+		/** How long a colour change may take, or `0` for "do not animate it".
+		*
+		* The same decision the wallpaper layer makes (`transitionPlan` over the global
+		* effect, the resolved duration and the OS preference), so the two halves of one
+		* switch can never disagree about whether they are animating. */
+		function paletteFadeMs() {
+			const tr = rTransition();
+			const plan = transitionPlan({
+				effect: tr.effect,
+				easing: tr.easing,
+				durationMs: rFadeMs(),
+				canAnimate: true,
+				reducedMotion: prefersReducedMotion()
+			});
+			return plan.animate ? plan.durationMs : 0;
+		}
+		/** Arm the fade for a palette change, or disarm it for anything else.
+		*
+		* `animate` is false on every pass that only moves an alpha (a slider drag): the
+		* tokens are rewritten there too, and a live transition would make the surface
+		* lag behind the pointer. */
+		function applyPaletteFade(animate) {
+			const initials = fadeInitialsOf(fadeTokenNames());
+			const css = paletteFadeCss({
+				selectors: FADE_SELECTORS,
+				initial: initials,
+				durationMs: animate ? paletteFadeMs() : 0,
+				easing: rTransition().easing
+			});
+			if (css === fadeCssCache) return;
+			fadeCssCache = css;
+			ensureFadeSheet().textContent = css;
+		}
+		/** Inline `transition` for an element the plugin paints itself; `0` disarms it. */
+		function fadeInlineFor(animate) {
+			return paletteFadeInline(animate ? paletteFadeMs() : 0, rTransition().easing);
+		}
 		const RIGHTBAR_STYLE_RULE = "div[data-sidebar-right-panel]:not(:has([data-dockkit-content],[data-dockkit-empty]))[data-sidebar-right-open],div[data-sidebar-right-panel] [data-dockkit-content]:not([data-dockkit-float]),div[data-sidebar-right-panel] [data-dockkit-empty]{background:var(--dsh-any-bg-rightbar,var(--dsw-alias-bg-base))!important}div[data-sidebar-right-panel][data-sidebar-right-open]{-webkit-backdrop-filter:var(--dsh-any-blur-rightbar,none);backdrop-filter:var(--dsh-any-blur-rightbar,none)}";
 		/** Paint the file-preview panel's surface from its own slider. */
 		function applyRightbarOverrides(op) {
@@ -2485,7 +2895,7 @@ window.__ModuleLoader__.load({
 		*  the frame. The frame's translucent bg-base sits UNDER the sidebar, so
 		*  reducing the main-bg opacity stacked a second alpha onto the sidebar; moving
 		*  the alpha onto the columns keeps the sidebar owned by its own slider. */
-		function applyPartOpacities(ops) {
+		function applyPartOpacities(ops, fade = false) {
 			discoverParts();
 			if (frameEl === null) return;
 			const base = palette()?.tokens["--dsw-alias-bg-base"];
@@ -2498,8 +2908,15 @@ window.__ModuleLoader__.load({
 				return;
 			}
 			frameEl.style.background = "transparent";
-			if (centerEl !== null) centerEl.style.background = withAlpha(base, ops.bg);
-			if (detailsEl !== null) detailsEl.style.background = withAlpha(base, ops.bg);
+			const transition = fadeInlineFor(fade);
+			if (centerEl !== null) {
+				centerEl.style.transition = transition;
+				centerEl.style.background = withAlpha(base, ops.bg);
+			}
+			if (detailsEl !== null) {
+				detailsEl.style.transition = transition;
+				detailsEl.style.background = withAlpha(base, ops.bg);
+			}
 		}
 		/** Blur of the option panels inside the settings dialog (.dab-card), owned by
 		*  the "dialog option panel" (card) blur slider. Written as a plugin-owned
@@ -2709,10 +3126,11 @@ window.__ModuleLoader__.load({
 			if (!tableFixStyleEl.isConnected) document.head.appendChild(tableFixStyleEl);
 		}
 		/** Re-derive the conversation view cards from the current config. */
-		function applyViewCards() {
+		function applyViewCards(fade = false) {
 			discoverParts();
 			if (centerEl === null) return;
 			const surface = palette()?.tokens["--dsw-alias-bg-layer-1"];
+			const transition = fadeInlineFor(fade);
 			VIEW_CARDS.forEach((spec, i) => {
 				const target = discoverViewTarget(i, spec);
 				if (target === null) return;
@@ -2722,6 +3140,7 @@ window.__ModuleLoader__.load({
 				if (!plain) {
 					if (!target.hasAttribute(spec.mark)) stashCardPrev(target, spec.prev, false);
 					const borderAlpha = opacity > 0 ? Math.min(1, opacity * 1.5) : blurPx > 0 ? .35 : 0;
+					target.style.transition = transition;
 					target.style.background = surface !== void 0 ? withAlpha(surface, opacity) : "transparent";
 					target.style.border = surface !== void 0 ? `1px solid ${withAlpha(surface, borderAlpha)}` : "1px solid transparent";
 					target.style.borderRadius = "16px";
@@ -2844,6 +3263,13 @@ window.__ModuleLoader__.load({
 			l.el.style.backgroundImage = "";
 			l.el.style.backgroundSize = "";
 			l.el.style.backgroundPosition = "";
+			l.el.style.transform = "none";
+		}
+		/** Write the two properties a switch animates. Both are always written, so a
+		*  layer can never keep half of a previous effect. */
+		function applyLayerStyle(el, style) {
+			el.style.opacity = style.opacity;
+			el.style.transform = style.transform;
 		}
 		/** Intrinsic-size cache for the center mode (native pixels of the current image). */
 		let imgNat = null;
@@ -2912,13 +3338,18 @@ window.__ModuleLoader__.load({
 				});
 			}
 		}
-		/** Whether a switch should animate: nothing to fade from, an invisible
-		*  wallpaper and a reduced-motion preference all switch instantly. */
-		function canFade(from) {
+		/** Whether there is anything to animate FROM: a wallpaper on screen that is
+		*  actually visible. The duration question belongs to `rFadeMs`, and the
+		*  `reduced-motion` veto to `transitionPlan` — this answers only the layer half,
+		*  so a first paint (no previous image) never fades in from nothing. */
+		function canAnimateFrom(from) {
 			if (from.url === null) return false;
-			if (rWop() <= .01) return false;
+			return rWop() > .01;
+		}
+		/** Whether the OS asks for reduced motion right now. */
+		function prefersReducedMotion() {
 			const mm = typeof window.matchMedia === "function" ? window.matchMedia("(prefers-reduced-motion: reduce)") : null;
-			return mm === null || !mm.matches;
+			return mm !== null && mm.matches;
 		}
 		/** End an in-flight fade: promote the incoming layer, free the one under it. */
 		function finishFade(idx) {
@@ -2931,6 +3362,7 @@ window.__ModuleLoader__.load({
 			front = idx;
 			const el = layers[idx].el;
 			el.style.opacity = "1";
+			el.style.transform = "none";
 			el.style.willChange = "";
 			clearLayer(layers[idx === 0 ? 1 : 0]);
 		}
@@ -2947,6 +3379,7 @@ window.__ModuleLoader__.load({
 			const el = layers[idx].el;
 			el.style.transition = "none";
 			el.style.opacity = "1";
+			el.style.transform = "none";
 			el.style.willChange = "";
 			clearLayer(layers[idx === 0 ? 1 : 0]);
 		}
@@ -2962,6 +3395,7 @@ window.__ModuleLoader__.load({
 			const el = layers[idx].el;
 			el.style.transition = "none";
 			el.style.opacity = "0";
+			el.style.transform = "none";
 			el.style.willChange = "";
 			clearLayer(layers[idx]);
 		}
@@ -2992,27 +3426,34 @@ window.__ModuleLoader__.load({
 			const idx = front === 0 ? 1 : 0;
 			const target = ls[idx];
 			const el = target.el;
+			const tr = rTransition();
+			const plan = transitionPlan({
+				effect: tr.effect,
+				easing: tr.easing,
+				durationMs: rFadeMs(),
+				canAnimate: canAnimateFrom(from),
+				reducedMotion: prefersReducedMotion()
+			});
 			el.style.transition = "none";
-			el.style.opacity = "0";
+			el.style.willChange = plan.willChange;
+			applyLayerStyle(el, plan.from);
 			el.style.zIndex = "1";
 			from.el.style.zIndex = "0";
 			paintLayer(target, url);
 			applyWpEffects();
-			const fadeMs = rFadeMs();
-			if (!canFade(from) || fadeMs <= 0) {
-				el.style.opacity = "1";
+			if (!plan.animate) {
+				applyLayerStyle(el, plan.to);
 				front = idx;
 				clearLayer(from);
 				return;
 			}
-			el.style.willChange = "opacity";
 			pending = idx;
 			requestAnimationFrame(() => {
 				if (pending !== idx || layers === null) return;
-				el.style.transition = `opacity ${fadeMs}ms ease`;
-				el.style.opacity = "1";
+				el.style.transition = plan.transition;
+				applyLayerStyle(el, plan.to);
 			});
-			fadeTimer = window.setTimeout(() => finishFade(idx), fadeMs + 160);
+			fadeTimer = window.setTimeout(() => finishFade(idx), plan.durationMs + 160);
 		}
 		function applyWpEffects() {
 			if (wpEl === null || layers === null) return;
@@ -3039,11 +3480,12 @@ window.__ModuleLoader__.load({
 				clearCustomTokens();
 				clearOwnedSurfaces();
 			}
-			applyCustomTokens(rOps());
+			const paletteMoved = applyCustomTokens(rOps());
 			applySettingsOverrides(rSop());
 			applyTrajectoryOverrides(rTrajectoryOpacity());
 			applyRightbarOverrides(rRightbarOpacity());
 			applyPartBlurs(rBlurs());
+			applyViewCards(paletteMoved);
 		}
 		function teardownWp() {
 			dropWpContainer();
@@ -5637,11 +6079,58 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region src/client/components/pages/ProfilePage.tsx
+		/** Chip labels, keyed by the value they set — so no chip can be built from a
+		*  value the schema does not accept, and `check:ui` still sees every key used. */
+		const EFFECT_KEYS = {
+			fade: "trEffectFade",
+			none: "trEffectNone",
+			zoom: "trEffectZoom",
+			slide: "trEffectSlide"
+		};
+		const EASING_KEYS = {
+			ease: "trEasingEase",
+			linear: "trEasingLinear",
+			"ease-out": "trEasingOut",
+			"ease-in-out": "trEasingInOut"
+		};
 		function ProfilePage({ p, notify }) {
-			const { t, exportTheme, importTheme } = p;
+			const { t, exportTheme, importTheme, setTransition } = p;
 			const importRef = (0, react.useRef)(null);
 			p.useStore((s) => s.rev + s.rulesRev);
 			const holidays = cfg.holidays;
+			const tr = cfg.transition;
+			const previewRef = (0, react.useRef)(null);
+			/** The OS preference, read at render: it vetoes the real switch (see
+			*  `transitionPlan`), so the card has to say so rather than show a preview of
+			*  something the interface will not do. */
+			const reduced = typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+			/**
+			* Play the effect on the preview swatch, for the duration a real switch would
+			* use right now: the wallpaper fading into ITSELF is invisible, which is the
+			* one thing a transition setting must not leave the user guessing about.
+			*/
+			const play = () => {
+				const el = previewRef.current;
+				if (el === null) return;
+				const plan = transitionPlan({
+					effect: tr.effect,
+					easing: tr.easing,
+					durationMs: rFadeMs(),
+					canAnimate: true,
+					reducedMotion: false
+				});
+				el.style.transition = "none";
+				el.style.opacity = plan.from.opacity;
+				el.style.transform = plan.from.transform;
+				requestAnimationFrame(() => {
+					el.style.transition = plan.transition;
+					el.style.opacity = plan.to.opacity;
+					el.style.transform = plan.to.transform;
+				});
+			};
+			(0, react.useEffect)(() => {
+				if (!reduced) play();
+			}, [tr.effect, tr.easing]);
 			const onImport = async (file) => {
 				try {
 					const ok = await importTheme(file);
@@ -5689,9 +6178,106 @@ window.__ModuleLoader__.load({
 						})]
 					})
 				}),
+				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
+					className: "dab-card dab-rise",
+					style: { "--d": 1 },
+					children: [
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							className: "dab-part-head",
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "dab-part-ico",
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SparkleIcon, { size: 16 })
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "dab-part-name",
+								children: t("trTitle")
+							})]
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "dab-swatch-title",
+							children: t("trEffect")
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "dab-chip-row",
+							children: TRANSITION_EFFECTS.map((effect) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: `dab-chip${tr.effect === effect ? " is-active" : ""}`,
+								onClick: () => setTransition({ effect }),
+								children: t(EFFECT_KEYS[effect])
+							}, effect))
+						}),
+						tr.effect === "none" ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "dab-swatch-title",
+							style: { marginTop: 12 },
+							children: t("trEasing")
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "dab-chip-row",
+							children: TRANSITION_EASINGS.map((easing) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+								type: "button",
+								className: `dab-chip${tr.easing === easing ? " is-active" : ""}`,
+								onClick: () => setTransition({ easing }),
+								children: t(EASING_KEYS[easing])
+							}, easing))
+						})] }),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "dab-swatch-title",
+							style: { marginTop: 12 },
+							children: t("trDuration")
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							style: { marginTop: 2 },
+							children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LiveSlider, {
+								label: t("trDuration"),
+								min: 0,
+								max: 3e3,
+								step: 50,
+								def: tr.durationMs,
+								fmt: (v) => `${v} ms`,
+								onInput: (v) => {
+									cfg.transition = normalizeTransition({
+										...cfg.transition,
+										durationMs: v
+									});
+									saveConfig();
+								},
+								onChange: (v) => setTransition({ durationMs: v })
+							})
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+							style: {
+								display: "flex",
+								alignItems: "center",
+								gap: 12,
+								marginTop: 13
+							},
+							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "dab-tr-preview",
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+									ref: previewRef,
+									className: "dab-tr-preview-in"
+								})
+							}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+								type: "button",
+								className: "dab-btn",
+								disabled: reduced,
+								onClick: play,
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(SparkleIcon, { size: 14 }), t("trPreview")]
+							})]
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							className: "dab-hint",
+							style: { marginTop: 10 },
+							children: t("trHint")
+						}),
+						reduced ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							className: "dab-hint",
+							style: { marginTop: 6 },
+							children: t("trReducedHint")
+						}) : null
+					]
+				}),
 				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 					className: "dab-profile-grid dab-rise",
-					style: { "--d": 2 },
+					style: { "--d": 3 },
 					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
 						className: "dab-card dab-card-hover",
 						children: [
@@ -5755,7 +6341,7 @@ window.__ModuleLoader__.load({
 				}),
 				/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("footer", {
 					className: "dab-footer dab-rise",
-					style: { "--d": 3 },
+					style: { "--d": 4 },
 					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 						className: "dab-footer-mono",
 						children: "dsh-background-by-model"
@@ -6642,6 +7228,24 @@ window.__ModuleLoader__.load({
 						saveConfig();
 						sync();
 					},
+					/**
+					* Patch the GLOBAL wallpaper-switch transition (effect, easing, where the
+					* duration comes from).
+					*
+					* Deliberately no `applyWp()`: this setting decides what the NEXT switch
+					* looks like and nothing on screen changes right now, so re-running the
+					* whole apply (token rewrite, every interface part) for something that
+					* paints nothing would be the expensive way to say "saved". The Config
+					* page's own preview plays the effect instead.
+					*/
+					setTransition: (patch) => {
+						cfg.transition = normalizeTransition({
+							...cfg.transition,
+							...patch
+						});
+						sync();
+						saveConfig();
+					},
 					setHolidaysEnabled: (v) => {
 						cfg.holidays.enabled = v;
 						persistConfig();
@@ -6657,7 +7261,7 @@ window.__ModuleLoader__.load({
 							if (url !== null) images[slot] = url;
 						}
 						const payload = {
-							version: 5,
+							version: 6,
 							exportedAt: (/* @__PURE__ */ new Date()).toISOString(),
 							config: cfg,
 							images