wallpaper-engine-dsh 1.0.3 → 1.0.5

package/README.md

@@ -10,17 +10,17 @@ A DSH bundle that turns your local **Wallpaper Engine** library into the live ba
 
 **Legibility on any wallpaper.** Text stays readable by construction, not by luck. The veil always opposes the text colour — black in the dark theme, white in the light theme — so neither a pitch-black nor a pure-white wallpaper can swallow the UI. On top of that, a Smart veil samples the wallpaper's brightness every few seconds and automatically strengthens the veil when a scene drifts too bright (or too dark) for the current theme; it also strengthens the border contrast and the glass frosting on the same evidence. Dropdowns, menus, and dialogs sit on DSH's opaque surfaces and are never affected.
 
-**Manual framing.** Pick a base layout — Cover, Contain, Stretch, or Original — then frame the shot yourself. **Adjust** opens the live wallpaper fullscreen: scroll to zoom in (up to 4×), drag to pan within the zoomed framing — the crop is clamped so the image always fills the screen with no exposed edges. Esc or Done finishes, the framing persists per selection, and **Reset crop** restores the default in one click. Web wallpapers can be framed the same way (zoom and pan apply to the iframe); the layout select only means something for video/stills and hides itself for web.
+**Manual framing.** Pick a base layout — Cover, Contain, Stretch, Original, or Free — then frame the shot yourself. **Adjust** opens the live wallpaper fullscreen: scroll to zoom, drag to pan. In the first four layouts the crop is clamped so the image always fills the screen with no exposed edges; **Free** places the wallpaper at natural size on a black canvas where it can be dragged anywhere and zoomed from 0.1× to 4×, with just enough kept on screen that it can never be dragged out of sight. Esc or Done finishes, the framing persists, and **Reset crop** restores the default in one click. Web wallpapers take the same select and the same zoom/pan framing — the transform applies to the iframe directly.
 
-**Four live sliders.** Wallpaper blur, Scrim, Borders, and Glass — every change lands instantly and persists. Blur never re-frames the picture: at any blur level the composition, layout, and crop are exactly what they are at zero blur — the wallpaper's edges are never silently cropped. Within one blur radius of the screen edge the picture fades softly into the veil, hidden under the UI chrome. A whisper of dither noise keeps smooth gradients band-free; and at zero blur the media bypasses the filter pipeline entirely for bit-exact pixels.
+**Four live sliders.** Wallpaper blur, Scrim, Borders, and Glass — every change lands instantly and persists. Blur renders in place: composition, layout, and crop stay identical at every blur level, and within one blur radius of the screen edge the picture fades softly into the veil beneath the UI chrome. A whisper of dither noise keeps smooth gradients band-free; at zero blur the media bypasses the filter pipeline entirely for bit-exact pixels.
 
-**Rotation lists.** Build any number of carousel lists, each with its own wallpapers, interval (1–120 min), and order (sequence or random). Your first playable Wallpaper Engine playlist is imported automatically on first run; any other playlist can be imported into any list.
+**Rotation lists.** Build any number of carousel lists, each with its own wallpapers, interval (1–120 min), and order (sequence or random). Auto-rotate arms once the active list holds at least two usable wallpapers; the status row always reports whether rotation is actually running. Your first playable Wallpaper Engine playlist is imported automatically on first run; any other playlist can be imported into any list.
 
 **Resource monitor.** A live FPS readout with a low-framerate hint, plus optional auto-pause when the tab is hidden or the battery runs low. `prefers-reduced-motion` starts videos paused.
 
 **Bilingual.** The UI follows the shell's Language setting (Chinese/English) with a manual override in the picker.
 
-**Resilient playback.** Switches and clears crossfade smoothly. A video the browser cannot decode retries once with fresh tokens, then falls back to its preview still with a note in the status row — and the next Refresh retries the live media. Inventory rebuilds re-issue URLs in the background without ever interrupting a playing stream.
+**Resilient playback.** Switches and clears crossfade smoothly. Media that repeatedly fails to decode retries once with fresh tokens, then falls back to the preview still with a note in the status row; an entry with nothing to fall back on is cleared rather than left on a dead layer — and the next Refresh retries the live media. Refresh re-issues every URL and swaps it into the live element in place, so playback position survives. Background inventory rebuilds reuse the same URLs and never touch a playing stream.
 
 ## Install
 

package/README.zh.md

@@ -2,25 +2,25 @@
 
 [English](README.md) | [中文](README.zh.md)
 
-一个 DSH bundle:把本机 **Wallpaper Engine** 壁纸库变成 DSH web GUI(`dsh web`)的动态背景。视频壁纸在聊天界面背后播放,网页壁纸原地渲染;交叉淡入、液态玻璃面板、随壁纸自适应的可读性遮罩、手动取景、轮播列表、搜索与中英双语界面,全部收拢在一个设置行里。
+一个 DSH bundle:把本机 **Wallpaper Engine** 壁纸库变成 DSH web GUI(`dsh web`)的动态背景。视频壁纸在聊天界面背后播放,网页壁纸直接渲染。交叉淡入、液态玻璃面板、随壁纸自适应的可读性遮罩、手动取景、轮播列表、搜索与中英双语界面,全部集中在一个设置行里。
 
 ## 功能
 
-**只列真正渲染得动的壁纸。** 网格中列出的是浏览器能真实渲染的全部类型——视频与网页壁纸。场景/应用壁纸是 Wallpaper Engine 私有的 `.pkg` 场景包,浏览器无法执行,因此直接从列表中过滤,而不是以降级的静态图充数。列出的每张都真实播放,按 视频/网页 标注类型;搜索框按标题或创意工坊 ID 即时筛选大库。
+**只列出能真实播放的壁纸。** 网格中列出浏览器可以真实渲染的全部类型——视频与网页壁纸。场景/应用壁纸是 Wallpaper Engine 私有的 `.pkg` 场景包,浏览器无法执行,因此直接过滤,不以降级的静态图代替。列出的每张壁纸都真实播放,并按 视频/网页 标注类型;搜索框可按标题或创意工坊 ID 筛选较大的壁纸库。
 
-**任意壁纸都可读。** 文字可读靠的是结构保障,不是运气。遮罩颜色始终与文字颜色相对——深色主题压黑、浅色主题提亮——无论纯黑还是纯白的壁纸都吞不掉界面。在此基础上,"智能可视"每隔几秒采样一次壁纸亮度,画面偏离当前主题的舒适区时自动加强遮罩。下拉菜单、弹窗等浮层坐在 DSH 原生的不透明表面上,从不受影响。
+**任何壁纸上文字都可读。** 遮罩颜色始终与文字颜色相反:深色主题用黑色遮罩,浅色主题用白色遮罩,因此过亮或过暗的壁纸都不会盖住文字。在此基础上,「智能可视」每隔几秒采样一次壁纸亮度,亮度过高或过低时自动加强遮罩。下拉菜单、弹窗等浮层显示在 DSH 原生的不透明表面上,不受影响。
 
-**手动取景。** 先选基础排布——填充、适应、拉伸、原始——然后自己构图:点「调整画面」把壁纸全屏展开,滚轮放大(最高 4×)、拖动在放大的画面内平移——裁剪范围经过钳制,画面永远铺满屏幕、不露边。Esc 或「完成」退出,取景随选择持久保存,「重置裁剪」一键还原。网页壁纸同样可以取景(缩放与平移对 iframe 生效);排布下拉只对视频/静态图有意义,网页壁纸自动隐藏。
+**手动取景。** 先选基础排布(填充、适应、拉伸、原始、自由),再手动调整画面:点「调整画面」将壁纸全屏展开,滚轮缩放,拖动平移。前四种排布下裁剪范围经过限制,画面始终铺满屏幕,不露出边缘;「自由」把壁纸按原始大小放在黑色画布上,可拖动到任意位置,缩放范围 0.1–4×,并始终保留一小块在屏幕内,不会拖丢。按 Esc 或点「完成」退出,取景设置会保存,「重置裁剪」可一键恢复默认。网页壁纸使用相同的排布下拉与缩放/平移取景(变换直接作用于 iframe)。
 
-**四个实时滑杆。** 壁纸模糊、暗化、边框、玻璃——每一步调节即时生效并持久保存。模糊从不改变取景:任意模糊度下画面的比例、排布与取景和模糊为零时完全一致,绝不偷偷裁掉壁纸四边;模糊半径内的屏幕边缘向遮罩自然过渡,被界面边饰覆盖,肉眼不可察。叠加微量抖动噪声消除渐变色带;模糊归零时媒体完全绕开滤镜管线,像素逐位精确。
+**四个实时滑杆。** 壁纸模糊、暗化、边框、玻璃,每一步调节立即生效并保存。模糊在原位渲染:任意模糊度下,画面的比例、排布与取景完全一致;屏幕边缘一个模糊半径内的画面向遮罩过渡,被界面边饰覆盖,通常不可见。模糊时叠加轻微噪声,消除渐变色带;模糊为零时媒体完全绕过滤镜管线,像素保持不变。
 
-**轮播列表。** 可建任意多个列表,各自拥有壁纸集合、切换间隔(1–120 分钟)和顺序(顺序/随机)。首次运行自动导入第一个可播放的 Wallpaper Engine 播放列表,其余列表可随时导入到任意列表。
+**轮播列表。** 可以创建任意多个列表,各自指定壁纸集合、切换间隔(1–120 分钟)与顺序(顺序/随机)。当前列表至少有两张可用壁纸时才会自动轮转;状态行始终显示轮转是否正在运行。首次运行会自动导入第一个可播放的 Wallpaper Engine 播放列表,其他播放列表也可随时导入到任意列表。
 
 **资源监控。** 实时帧率读数与低帧率提示,页面隐藏或电量不足时可选自动暂停。系统开启 `prefers-reduced-motion` 时视频默认暂停。
 
-**中英双语。** 界面跟随 DSH 的"语言"设置(中/英),面板内亦可手动指定。
+**中英双语。** 界面跟随 DSH 的「语言」设置(中/英),也可在面板中手动指定。
 
-**播放有韧性。** 切换与关闭都平滑淡入淡出。浏览器解不了的视频先换新令牌重试一次,仍失败则退到预览图并在状态行注明——下次「刷新」自动重试原媒体。后台重建清单时静默更换 URL,绝不掐断正在播放的流。
+**播放出错自动恢复。** 切换与关闭均以淡入淡出过渡。媒体连续解码失败时,先使用新令牌重试一次;仍失败则改用预览图,并在状态行说明;没有预览可用的条目则清空选择,避免黑屏。下次「刷新」会重新尝试原媒体。刷新会更新全部 URL,并直接替换正在播放的元素的地址,播放进度保留。后台重建清单时复用相同 URL,不会中断正在播放的流。
 
 ## 安装
 
@@ -40,8 +40,8 @@ dsh plugin --profile web add link:<克隆文件夹的绝对路径>
 ## 使用
 
 1. 从缩略图网格选择壁纸,它会在界面背后淡入。壁纸库较大时用搜索框快速定位。
-2. **暂停/播放** 控制视频播放;**关闭** 淡出壁纸;**刷新** 重新扫描壁纸库——新订阅的创意工坊壁纸无需重载页面即可出现,已降级的壁纸也会重试原媒体。
-3. 用滑杆调节融合效果。壁纸太花时调高 **暗化** 和 **边框** 直到文字清晰;开启智能可视后这些自动完成。界面跟随 DSH 明暗主题,无需手动适配。
+2. **暂停/播放** 控制视频播放;**关闭** 淡出壁纸;**刷新** 重新扫描壁纸库——新订阅的创意工坊壁纸无需重载页面即可出现,已改用预览图的壁纸也会重新尝试播放原媒体。
+3. 用滑杆调节融合效果。壁纸画面复杂时调高 **暗化** 和 **边框** 直到文字清晰;开启智能可视后这些自动完成。界面跟随 DSH 明暗主题,无需手动适配。
 4. **排布** 一行决定基础摆放,点「调整画面」在画布上直接拖动平移、滚轮缩放取景。
 5. 用 **新建** 创建轮播列表,从网格挑选或导入 WE 播放列表,然后开启 **自动轮转**。
 6. 资源行显示当前帧率与两个自动暂停开关。
@@ -56,9 +56,9 @@ bundle 分为两半:
   - `GET /we-background/inventory[?refresh=1]`
   - `GET /we-background/media/<token>[/<入口文件或子资源>…]` —— 支持 HTTP Range,视频可拖动进度。网页壁纸的 URL 直接定位到入口文件(如 `…/media/<token>/index.html`),文档 URL 与壁纸目录结构一一对应,壁纸内部的相对引用(脚本、样式、图片、fetch)按 Wallpaper Engine 自身的规则解析;媒体响应带 `Access-Control-Allow-Origin: *`,沙箱 iframe(不透明源)里的壁纸也能 fetch 自己的资源
   - `GET /we-background/preview/<token>`
-- **浏览器插件** 把选中的壁纸渲染在应用框架之下的固定层,提供设置界面,所有视觉效果都读 DSH 设计令牌,主题切换自然生效。
+- **浏览器插件** 把选中的壁纸渲染在应用框架之下的固定层,提供设置界面,所有视觉效果都读取 DSH 设计令牌,主题切换时自动适配。
 
-媒体服务在每一层都有防御:令牌是不可猜测的 72 位随机值,跨清单重建保持稳定(后台刷新绝不掐断播放中的流),仅在显式刷新时重铸;子资源路径先做词法包含检查,再对照真实文件系统复核,符号链接逃不出壁纸目录;HTML 与 SVG 响应带 `sandbox` CSP,永远无法以 DSH 源的身份执行;媒体响应的 CORS 通配只让"知道令牌的人读到本来就能请求的文件",能力边界仍是令牌本身,且整个服务只监听回环;会短斤缺两的响应自我销毁,而不是悄悄截断。清单由宿主缓存 30 秒,安装发现在请求路径之外异步解析并缓存 10 分钟。本插件不注册模型工具,不占用 prompt。
+媒体服务在多个层面做了防护:令牌是无法猜测的 72 位随机值,清单重建时保持不变(后台刷新不会中断正在播放的流),只在显式刷新时重新生成;子资源路径先做词法包含检查,再对照真实文件系统复核,符号链接无法指向壁纸目录之外;HTML 与 SVG 响应带 `sandbox` CSP,不能以 DSH 源的身份执行;媒体响应的 CORS 通配只允许持有令牌的一方读取其本来就能请求的文件,访问权限仍由令牌决定,且整个服务只监听本机回环地址;长度不足的响应会直接中断,而不是悄悄截断。清单由宿主缓存 30 秒;安装位置的发现过程在请求路径之外异步执行,并缓存 10 分钟。本插件不注册模型工具,不占用 prompt。
 
 ## 限制
 

package/lib/client.js

@@ -91,6 +91,7 @@ window.__ModuleLoader__.load({
 		    fitContain: "适应",
 		    fitFill: "拉伸",
 		    fitNone: "原始",
+		    fitFree: "自由",
 		    adjust: "调整画面",
 		    adjustDone: "完成",
 		    adjustHint: "拖动平移 · 滚轮缩放 · Esc 或点「完成」退出",
@@ -168,6 +169,7 @@ window.__ModuleLoader__.load({
 		    fitContain: "Contain",
 		    fitFill: "Stretch",
 		    fitNone: "Original",
+		    fitFree: "Free",
 		    adjust: "Adjust",
 		    adjustDone: "Done",
 		    adjustHint: "Drag to pan · wheel to zoom · Esc or Done to exit",
@@ -226,7 +228,7 @@ window.__ModuleLoader__.load({
 		  offsetY: 0,
 		};
 
-		const FIT_MODES = ["cover", "contain", "fill", "none"];
+		const FIT_MODES = ["cover", "contain", "fill", "none", "free"];
 
 		// ── Persisted selection ─────────────────────────────────────────────────────
 		function clampNum(v, lo, hi, fallback) {
@@ -273,11 +275,12 @@ window.__ModuleLoader__.load({
 		      autoScrim: o.autoScrim !== false,
 		      lang: o.lang === "zh" || o.lang === "en" ? o.lang : "auto",
 		      fit: FIT_MODES.indexOf(o.fit) >= 0 ? o.fit : DEFAULTS.fit,
-		      // Older builds could persist zoom < 1 / unclamped pans — clampCrop()
-		      // at store creation re-seats both into the gap-free envelope.
-		      zoom: clampNum(o.zoom, 0.25, 4, DEFAULTS.zoom),
-		      offsetX: clampNum(o.offsetX, -200, 200, DEFAULTS.offsetX),
-		      offsetY: clampNum(o.offsetY, -200, 200, DEFAULTS.offsetY),
+		      // Older builds could persist unclamped crops — clampCrop() at store
+		      // creation re-seats both into the envelope the CURRENT fit mode
+		      // allows (free: zoom ≥ 0.1 with keep-visible pans; others: gap-free).
+		      zoom: clampNum(o.zoom, 0.1, 4, DEFAULTS.zoom),
+		      offsetX: clampNum(o.offsetX, -300, 300, DEFAULTS.offsetX),
+		      offsetY: clampNum(o.offsetY, -300, 300, DEFAULTS.offsetY),
 		    };
 		  } catch {
 		    return { id: "", ...DEFAULTS };
@@ -302,8 +305,8 @@ window.__ModuleLoader__.load({
 		  inventory: { installDir: null, wallpapers: [], total: 0, portableCount: 0, playlists: [], error: null },
 		  loaded: false,
 		};
-		// Older builds allowed zoom < 1 and unclamped pans — re-seat any persisted
-		// crop into the gap-free envelope before the first render.
+		// Re-seat any persisted crop into the envelope the persisted fit mode
+		// allows before the first render.
 		clampCrop();
 
 		const listeners = new Set();
@@ -403,16 +406,15 @@ window.__ModuleLoader__.load({
 		    selection.rotationGroupId = "";
 		    persistSelection();
 		  }
-		  if (selection.rotationEnabled) {
-		    if (!selection.rotationGroupId) {
-		      const usable = firstUsableGroup();
-		      if (usable) selection.rotationGroupId = usable.id;
-		      else selection.rotationEnabled = false;
-		    } else if (rotationCandidates().length < 2) {
-		      const usable = firstUsableGroup();
-		      if (usable && usable.id !== selection.rotationGroupId) selection.rotationGroupId = usable.id;
-		      else if (!usable) selection.rotationEnabled = false;
-		    }
+		  // Rotation bookkeeping. A chosen list is never migrated away from — a
+		  // list with fewer than 2 usable wallpapers simply keeps rotation
+		  // disarmed (the timer needs a pair to alternate), and a hand-picked
+		  // wallpaper outside the active list keeps playing until the next
+		  // rotation tick brings the list back around.
+		  if (selection.rotationEnabled && !selection.rotationGroupId) {
+		    const usable = firstUsableGroup();
+		    if (usable) selection.rotationGroupId = usable.id;
+		    else selection.rotationEnabled = false;
 		    persistSelection();
 		  }
 
@@ -421,10 +423,6 @@ window.__ModuleLoader__.load({
 		    selection.id = "";
 		    persistSelection();
 		  }
-		  if (selection.rotationEnabled && selection.id && !rotationCandidates().some((w) => w.id === selection.id)) {
-		    selection.id = "";
-		    persistSelection();
-		  }
 		  if (!selection.id && selection.rotationEnabled) {
 		    const first = rotationCandidates()[0];
 		    if (first) selection.id = first.id;
@@ -720,9 +718,10 @@ window.__ModuleLoader__.load({
 		      // The media itself is unusable here — fall back to the still preview.
 		      demotedToPreview.add(id);
 		      applySelection(id);
-		    } else if (!w || (!w.preview && !w.media)) {
-		      // Nothing renderable at all (preview-less or vanished from the
-		      // inventory): clear the selection instead of a black screen loop.
+		    } else {
+		      // Unrenderable here with no preview to fall back on (or the entry has
+		      // vanished from the inventory entirely): clear the selection rather
+		      // than leave a dead element on the layer.
 		      applySelection("");
 		    }
 		  });
@@ -733,17 +732,33 @@ window.__ModuleLoader__.load({
 		// never receive pointer events. Adjust mode moves the LIVE layer node into a
 		// topmost transparent overlay — the user edits the real thing, WYSIWYG.
 		//
-		// Crop geometry invariants: the media box covers the viewport exactly at
-		// zoom 1; zooming creates headroom, panning spends it. Zoom floors at 1
-		// and pan is clamped to ±(zoom-1)/2·100 %, so a gap-free fullscreen image
-		// is guaranteed at every setting.
+		// Crop geometry is chosen by the fit mode. The four object-fit modes keep a
+		// GAP-FREE invariant: the media box covers the viewport exactly at zoom 1,
+		// zoom floors at 1, and pan is clamped to ±(zoom−1)/2·100 % — the image
+		// always fills the screen. The "free" mode drops that invariant on purpose:
+		// the media sits at natural size on a black canvas, zoom runs 0.1–4×, and
+		// pan is only clamped to keep a sliver (≥10 % of the box) on screen so the
+		// wallpaper can never be dragged entirely out of sight.
 		function clampCrop() {
-		  selection.zoom = Math.round(Math.min(4, Math.max(1, selection.zoom)) * 100) / 100;
+		  selection.zoom = Math.round(Math.min(4, Math.max(isFreeFit() ? 0.1 : 1, selection.zoom)) * 100) / 100;
+		  if (isFreeFit()) {
+		    // Content spans ±zoom·50 % of the box around its centre; the pan offset
+		    // shifts it by its own % of the box. |offset| ≤ (zoom+1)·50 − 10 keeps
+		    // at least 10 % of the media edge-to-edge visible in both axes.
+		    const reach = (selection.zoom + 1) * 50 - 10;
+		    selection.offsetX = Math.min(reach, Math.max(-reach, selection.offsetX));
+		    selection.offsetY = Math.min(reach, Math.max(-reach, selection.offsetY));
+		    return;
+		  }
 		  const pan = (selection.zoom - 1) * 50;
 		  selection.offsetX = Math.min(pan, Math.max(-pan, selection.offsetX));
 		  selection.offsetY = Math.min(pan, Math.max(-pan, selection.offsetY));
 		}
 
+		function isFreeFit() {
+		  return selection.fit === "free";
+		}
+
 		let adjustOverlay = null;
 		let adjustCleanup = null;
 
@@ -801,7 +816,7 @@ window.__ModuleLoader__.load({
 		    const h = overlay.clientHeight || 1;
 		    selection.offsetX += ((e.clientX - drag.x) / w) * 100;
 		    selection.offsetY += ((e.clientY - drag.y) / h) * 100;
-		    clampCrop(); // gap-free guarantee: pan never outruns the zoom headroom
+		    clampCrop(); // mode envelope: gap-free pan headroom, or free keep-visible
 		    drag = { x: e.clientX, y: e.clientY };
 		    applyEffects();
 		  };
@@ -819,10 +834,10 @@ window.__ModuleLoader__.load({
 		  };
 		  const onWheel = (e) => {
 		    if (typeof e.preventDefault === "function") e.preventDefault();
-		    // Crop semantics: zoom IN only (1–4×). Zooming below cover would float a
-		    // shrunken box in empty space — that is not a crop. Tightening zoom also
-		    // re-clamps the pan into the new headroom, so zooming back to 1 pulls
-		    // the framing home instead of leaving edge gaps.
+		    // clampCrop enforces the mode's zoom floor: the gap-free modes never
+		    // zoom below 1 (a shrunken box floating in empty space is not a crop)
+		    // and tightening zoom re-clamps the pan so zooming back to 1 pulls the
+		    // framing home; free mode shrinks down to 0.1× on its black canvas.
 		    selection.zoom *= Math.exp(-(e.deltaY || 0) * 0.0012);
 		    clampCrop();
 		    applyEffects();
@@ -876,6 +891,30 @@ window.__ModuleLoader__.load({
 		  return token;
 		}
 
+		/**
+		 * Swap re-minted URLs into the LIVE media element instead of remounting.
+		 * An explicit refresh re-mints every token, so the element's old URL is
+		 * already dead — the next seek or buffer-miss would 404 on it and trigger
+		 * a full recovery restart. Hot-swapping keeps the element identity (and
+		 * for video, the playback position) intact across the token change.
+		 */
+		function refreshLiveMediaUrls(layer) {
+		  const video = layer.querySelector("video");
+		  if (video && video.getAttribute("src") !== selection.url) {
+		    const at = video.currentTime;
+		    video.src = selection.url;
+		    if (at > 0) {
+		      video.addEventListener("loadedmetadata", () => {
+		        try { video.currentTime = at; } catch { /* not seekable yet */ }
+		      }, { once: true });
+		    }
+		  }
+		  const img = layer.querySelector("img");
+		  if (img && img.getAttribute("src") !== selection.url) img.src = selection.url;
+		  const frame = layer.querySelector("iframe");
+		  if (frame && frame.getAttribute("src") !== selection.url) frame.src = selection.url;
+		}
+
 		function syncLayers() {
 		  const existing = document.getElementById(LAYER_ID);
 
@@ -887,7 +926,9 @@ window.__ModuleLoader__.load({
 		    const gotKey = existing && existing.dataset.webgKey;
 
 		    if (existing && gotKey === wantKey && !forceRemount) {
-		      // Same wallpaper — only play/pause may have changed.
+		      // Same wallpaper — adopt any re-minted URL, then only play/pause may
+		      // have changed.
+		      refreshLiveMediaUrls(existing);
 		    } else {
 		      forceRemount = false;
 		      // Crossfade: the new layer fades in over the old one; the old layer
@@ -1022,8 +1063,11 @@ window.__ModuleLoader__.load({
 		    selection.wallpaperBlur > 0 ? (0.02 + selection.wallpaperBlur * 0.0004).toFixed(4) : "0");
 		  // Canvas fit: object-fit base mode plus the user's manual crop — pan
 		  // offsets (percent of the media box) and zoom, applied as a transform so
-		  // no remount is ever needed while dragging.
-		  s.setProperty("--webg-fit", selection.fit);
+		  // no remount is ever needed while dragging. "free" draws at natural size
+		  // (object-fit: none) and paints the layer black, so exposed edges read as
+		  // a canvas instead of whatever sits behind the app frame.
+		  s.setProperty("--webg-fit", selection.fit === "free" ? "none" : selection.fit);
+		  s.setProperty("--webg-layer-bg", selection.fit === "free" ? "#000" : "transparent");
 		  s.setProperty("--webg-zoom", String(selection.zoom));
 		  s.setProperty("--webg-offset-x", selection.offsetX + "%");
 		  s.setProperty("--webg-offset-y", selection.offsetY + "%");
@@ -1049,6 +1093,7 @@ window.__ModuleLoader__.load({
 		  s.removeProperty("--webg-noise-display");
 		  s.removeProperty("--webg-noise-opacity");
 		  s.removeProperty("--webg-fit");
+		  s.removeProperty("--webg-layer-bg");
 		  s.removeProperty("--webg-zoom");
 		  s.removeProperty("--webg-offset-x");
 		  s.removeProperty("--webg-offset-y");
@@ -1246,6 +1291,10 @@ window.__ModuleLoader__.load({
 
 		function onFit(e) {
 		  selection.fit = FIT_MODES.indexOf(e.target.value) >= 0 ? e.target.value : "cover";
+		  // Re-seat the crop into the new mode's envelope: leaving free for a
+		  // gap-free mode pulls zoom back up to 1 and reins the pan in; the other
+		  // direction only ever relaxes bounds, so the framing carries over.
+		  clampCrop();
 		  persistSelection();
 		  applyEffects();
 		  emit();
@@ -1474,19 +1523,20 @@ window.__ModuleLoader__.load({
 
 		function EffectsPanel(t, sel) {
 		  return React.createElement(React.Fragment, null,
-		    // object-fit only means something for video/still wallpapers — an
-		    // iframe ignores it and always fills its layer — so the base-mode
-		    // select is hidden for web. The manual crop (drag / wheel in the
-		    // adjust overlay) is a plain CSS transform and applies to EVERY kind,
-		    // so 调整画面 / 重置裁剪 stay available even for iframes.
+		    // The fit select covers all wallpaper types: for video/stills it picks
+		    // the object-fit base mode, and "free" additionally unlocks shrink +
+		    // off-edge dragging for every kind — an iframe ignores object-fit, but
+		    // the zoom/pan transform applies to it the same way. The manual crop
+		    // (drag / wheel in the adjust overlay) is a plain CSS transform and
+		    // applies to EVERY kind, so 调整画面 / 重置裁剪 are always available.
 		    React.createElement("div", { className: "webg-row webg-fit-row" },
-		      sel.type !== "web" && React.createElement("span", { className: "webg-hint webg-label" }, t.fit),
-		      sel.type !== "web" && React.createElement("select", {
+		      React.createElement("span", { className: "webg-hint webg-label" }, t.fit),
+		      React.createElement("select", {
 		        className: "webg-select webg-fit-select",
 		        value: sel.fit,
 		        onChange: onFit,
 		      },
-		      ...[t.fitCover, t.fitContain, t.fitFill, t.fitNone].map((label, i) =>
+		      ...[t.fitCover, t.fitContain, t.fitFill, t.fitNone, t.fitFree].map((label, i) =>
 		        React.createElement("option", { key: FIT_MODES[i], value: FIT_MODES[i] }, label),
 		      )),
 		      React.createElement("button", {
@@ -1537,13 +1587,17 @@ window.__ModuleLoader__.load({
 		}
 
 		function StatusRow(t, sel, group, usableCount, usableTotal) {
+		  // "Auto-rotating" is claimed only when the timer is genuinely armed —
+		  // rotation may be enabled on a list with fewer than 2 usable wallpapers,
+		  // in which case nothing switches until the list grows.
+		  const rotating = sel.rotationEnabled && usableCount >= 2;
 		  return React.createElement("div", { className: "webg-row" },
 		    React.createElement("span", { className: "webg-hint" },
 		      (group
 		        ? t.statusGroup(group.name, group.wallpaperIds.length, usableCount, group.interval,
 		            group.order === "random" ? t.random : t.sequence)
 		        : t.statusUsable(usableTotal)) +
-		      (sel.rotationEnabled ? " · " + t.autoRotating : "") +
+		      (rotating ? " · " + t.autoRotating : "") +
 		      (sel.autoPauseReasons.size > 0 ? " · " + t.autoPaused : "") +
 		      (sel.id && demotedToPreview.has(sel.id) ? " · " + t.decodeFallback : "") +
 		      (sel.inventory.installDir ? " · " + sel.inventory.installDir : "")),
@@ -1597,10 +1651,13 @@ window.__ModuleLoader__.load({
 		// Everything reads DSH design tokens (--dsw-*) so the UI blends into the
 		// shell and follows light/dark theme switches automatically.
 		const CSS = `
-		  /* Wallpaper layers: fixed, sunk below the app frame, crossfading. */
+		  /* Wallpaper layers: fixed, sunk below the app frame, crossfading. The
+		     background paints black only in the "free" fit mode, where the media
+		     can be dragged off the edges and the exposed area reads as a canvas. */
 		  .webg-layer {
 		    position: fixed; inset: 0; z-index: -2; overflow: hidden;
 		    pointer-events: none; opacity: 1;
+		    background: var(--webg-layer-bg, transparent);
 		    transition: opacity ${CROSSFADE_MS}ms ease;
 		  }
 		  .webg-layer--enter { opacity: 0; }

package/lib/index.js

@@ -175,15 +175,20 @@ export function createRouteRegistrar(webServer, opts = {}) {
     const fresh = discoveryCache && Date.now() - discoveryCache.at < discoveryTtlMs;
     if (!force && fresh) return discoveryCache.value;
     // Concurrent callers (registration warm-up + first request) share ONE
-    // discovery run instead of racing reg.exe twice at cold start.
+    // discovery run instead of racing reg.exe twice at cold start. A forced
+    // run deliberately does not join an in-flight non-forced one; either way,
+    // a run only releases the slot it still owns — clearing it unconditionally
+    // would kill another run's join promise, never clearing it would pin the
+    // slot to a settled promise and freeze TTL re-discovery forever.
     if (discovering && !force) return discovering;
-    discovering = discoverFn()
+    const run = discoverFn()
       .then((value) => {
         discoveryCache = { at: Date.now(), value };
         return value;
       })
-      .finally(() => { if (!force) discovering = null; });
-    return discovering;
+      .finally(() => { if (discovering === run) discovering = null; });
+    discovering = run;
+    return run;
   }
 
   async function buildInventory(force) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wallpaper-engine-dsh",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Wallpaper Engine library as the DSH web GUI background — video/web/still wallpapers, rotation lists, search, resource monitor, bilingual UI.",
   "type": "module",
   "main": "lib/index.js",