wallpaper-engine-dsh 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Weilv-D
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -34,7 +34,7 @@ Restart `dsh web`, then open **Settings → General → Wallpaper Engine**.
 
 1. Pick a wallpaper from the thumbnail grid — it fades in behind the app. Use the search box to narrow large libraries.
 2. **Pause/Play** controls video playback; **Close** fades the wallpaper out; **Refresh** rescans the library (new workshop subscriptions appear without reloading the page).
-3. Tune the blend with the sliders. On busy wallpapers, raise **Scrim** and **Borders** until text is comfortable; the UI follows DSH's light/dark theme automatically.
+3. Tune the blend with the sliders. On busy wallpapers, raise **Scrim** and **Borders** until text is comfortable; the UI follows DSH's light/dark theme automatically. The **Fit/Align** row sets how video and still wallpapers sit on the canvas (cover/contain/stretch/original, five anchor points).
 4. Create rotation lists with **New**, fill them from the grid or import a WE playlist, then enable **Auto-rotate**.
 5. The resource row shows the current frame rate and offers two auto-pause switches. `prefers-reduced-motion` starts videos paused.
 6. The Language control switches the picker between Chinese and English; on Auto it follows the shell setting.
@@ -49,9 +49,9 @@ The bundle has two halves:
   - `GET /we-background/inventory[?refresh=1]`
   - `GET /we-background/media/<token>[/asset…]` — with HTTP Range support for video seeking; web wallpapers can fetch their bundled sub-assets
   - `GET /we-background/preview/<token>`
-- A **browser plugin** renders the chosen wallpaper on a fixed layer behind the app frame, contributes the settings UI, and keeps every effect on DSH design tokens so themes apply cleanly.
+- A **browser plugin** renders the chosen wallpaper on a fixed layer behind the app frame, contributes the settings UI, and keeps every effect on DSH design tokens so themes apply cleanly. Wallpaper blur is clipped overscan (no content warping) with a whisper of dither noise to keep gradients band-free; a video the browser cannot decode falls back to the wallpaper's preview image.
 
-The host answers from a 30-second inventory cache; discovery is resolved once at startup and reused. The bundle registers no model tools and adds no prompt text.
+The host answers from a 30-second inventory cache with stable per-wallpaper tokens (an in-flight stream is never killed by a background rebuild); discovery is resolved asynchronously and cached for ten minutes. The bundle registers no model tools and adds no prompt text.
 
 ## Limitations
 

package/README.zh.md

@@ -34,7 +34,7 @@ dsh plugin --profile web add link:<克隆文件夹的绝对路径>
 
 1. 从缩略图网格选择壁纸，它会在界面背后淡入。壁纸库较大时用搜索框快速定位。
 2. **暂停/播放** 控制视频播放；**关闭** 淡出壁纸；**刷新** 重新扫描壁纸库，新订阅的创意工坊壁纸无需刷新页面即可出现。
-3. 用滑杆调节融合效果。壁纸太花时调高 **暗化** 和 **边框** 直到文字清晰；界面跟随 DSH 明暗主题自动适配。
+3. 用滑杆调节融合效果。壁纸太花时调高 **暗化** 和 **边框** 直到文字清晰；界面跟随 DSH 明暗主题自动适配。**排布/对齐** 一行设置视频与静态壁纸在画布上的摆放（填充/适应/拉伸/原始，五个锚点）。
 4. 用 **新建** 创建轮播列表，从网格挑选或导入 WE 播放列表，然后开启 **自动轮转**。
 5. 资源行显示当前帧率，并提供两个自动暂停开关。系统开启 `prefers-reduced-motion` 时视频默认暂停。
 6. "语言"控件在中英文之间切换面板；选"自动"则跟随 DSH 的语言设置。
@@ -49,9 +49,9 @@ bundle 分为两半：
   - `GET /we-background/inventory[?refresh=1]`
   - `GET /we-background/media/<token>[/资源…]` —— 支持 HTTP Range，视频可拖动进度；网页壁纸可加载其打包的子资源
   - `GET /we-background/preview/<token>`
-- **浏览器插件** 把选中的壁纸渲染在应用框架之下的固定层，提供设置界面，所有视觉效果都读 DSH 设计令牌，主题切换自然生效。
+- **浏览器插件** 把选中的壁纸渲染在应用框架之下的固定层，提供设置界面，所有视觉效果都读 DSH 设计令牌，主题切换自然生效。壁纸模糊采用裁边式超采样（内容不变形），叠加微量抖动噪声消除渐变色带；浏览器解不了的视频会自动改用该壁纸的预览图。
 
-清单由宿主缓存 30 秒；安装发现只解析一次。本插件不注册模型工具，不占用 prompt。
+清单由宿主缓存 30 秒，媒体令牌按壁纸稳定复用（后台重建不会掐断播放中的流）；安装发现异步执行并缓存 10 分钟。本插件不注册模型工具，不占用 prompt。
 
 ## 限制
 

package/lib/client.js

@@ -102,6 +102,8 @@ window.__ModuleLoader__.load({
 		    confirmDelete: (name) => "删除轮播列表「" + name + "」?",
 		    defaultGroupName: (n) => "轮播列表 " + n,
 		    defaultGroupBase: "轮播列表",
+		    iframeTitle: "Wallpaper Engine 网页壁纸",
+		    decodeFallback: "媒体无法解码,已改用预览图",
 		  },
 		  en: {
 		    settingsLabel: "Wallpaper Engine",
@@ -178,6 +180,8 @@ window.__ModuleLoader__.load({
 		    confirmDelete: (name) => "Delete rotation list \"" + name + "\"?",
 		    defaultGroupName: (n) => "Rotation list " + n,
 		    defaultGroupBase: "Rotation list",
+		    iframeTitle: "Wallpaper Engine web wallpaper",
+		    decodeFallback: "Media cannot be decoded here — showing the preview image",
 		  },
 		};
 
@@ -260,7 +264,7 @@ window.__ModuleLoader__.load({
 		      wallpaperBlur: clampNum(o.wallpaperBlur, 0, 60, DEFAULTS.wallpaperBlur),
 		      rotationEnabled: o.rotationEnabled === true,
 		      rotationGroupId: typeof o.rotationGroupId === "string" ? o.rotationGroupId : "",
-		      rotationGroups: readRotationGroups(o.rotationGroups, STRINGS.zh.defaultGroupBase),
+		      rotationGroups: readRotationGroups(o.rotationGroups, STRINGS[browserLang() || "zh"].defaultGroupBase),
 		      rotationSeeded: o.rotationSeeded === true,
 		      pauseOnHidden: o.pauseOnHidden !== false,
 		      pauseOnBattery: o.pauseOnBattery !== false,
@@ -493,9 +497,14 @@ window.__ModuleLoader__.load({
 		}
 
 		function startCreateGroup() {
+		  // Default names must stay unique even after deletions: take the smallest
+		  // free index instead of count+1.
+		  const taken = new Set(selection.rotationGroups.map((g) => g.name));
+		  let n = 1;
+		  while (taken.has(S().defaultGroupName(n))) n++;
 		  selection.editing = {
 		    id: nextGroupId(),
-		    name: S().defaultGroupName(selection.rotationGroups.length + 1),
+		    name: S().defaultGroupName(n),
 		    interval: DEFAULTS.rotationInterval,
 		    order: "sequence",
 		    wallpaperIds: [],
@@ -513,7 +522,7 @@ window.__ModuleLoader__.load({
 		    interval: clampNum(draft.interval, 1, 1440, DEFAULTS.rotationInterval),
 		    order: draft.order === "random" ? "random" : "sequence",
 		    wallpaperIds: Array.isArray(draft.wallpaperIds)
-		      ? draft.wallpaperIds.filter((x) => typeof x === "string" && x)
+		      ? [...new Set(draft.wallpaperIds.filter((x) => typeof x === "string" && x))]
 		      : [],
 		  };
 		  if (idx >= 0) selection.rotationGroups[idx] = cleaned;
@@ -522,8 +531,13 @@ window.__ModuleLoader__.load({
 		  selection.editing = null;
 		  if (selection.rotationEnabled && !rotationCandidates().some((w) => w.id === selection.id)) {
 		    const first = rotationCandidates()[0];
-		    applySelection(first ? first.id : "");
-		    return;
+		    if (first) {
+		      applySelection(first.id);
+		      return;
+		    }
+		    // Saved list has nothing usable — keep the current wallpaper and simply
+		    // stop rotation instead of clearing the screen.
+		    selection.rotationEnabled = false;
 		  }
 		  persistSelection();
 		  syncRotationTimer();
@@ -556,7 +570,7 @@ window.__ModuleLoader__.load({
 		function importPlaylistIntoDraft(playlist) {
 		  if (!selection.editing || !playlist || !Array.isArray(playlist.wallpaperIds)) return;
 		  const usable = new Set(selectableInventory().map((w) => w.id));
-		  selection.editing.wallpaperIds = playlist.wallpaperIds.filter((id) => usable.has(id));
+		  selection.editing.wallpaperIds = [...new Set(playlist.wallpaperIds.filter((id) => usable.has(id)))];
 		  emit();
 		}
 
@@ -566,10 +580,12 @@ window.__ModuleLoader__.load({
 		  const w = selection.id
 		    ? selection.inventory.wallpapers.find((x) => x.id === selection.id)
 		    : null;
-		  if (isPlayable(w)) {
+		  if (isPlayable(w) && !demotedToPreview.has(selection.id)) {
 		    selection.url = w.media;
 		    selection.type = w.type; // "video" | "web"
-		  } else if (w && isStatic(w)) {
+		  } else if (w && w.preview) {
+		    // Static path: scene/application wallpapers, and playable wallpapers
+		    // demoted after repeated media failures (undecodable container…).
 		    selection.url = w.preview;
 		    selection.type = "image";
 		  } else {
@@ -592,11 +608,27 @@ window.__ModuleLoader__.load({
 		  return selection.playing && selection.autoPauseReasons.size === 0;
 		}
 
+		// Latest known battery state (null until getBattery resolves). Kept at module
+		// scope so re-enabling the toggle can re-evaluate immediately instead of
+		// waiting for the next battery event.
+		let batteryState = null;
+		function applyBatteryPause() {
+		  if (!batteryState || !selection.pauseOnBattery) return;
+		  setAutoPause("battery",
+		    !batteryState.charging && batteryState.level <= BATTERY_SAVER_LEVEL);
+		}
+
 		// ── Behind-body layer: wallpaper + scrim, with crossfade ────────────────────
 		// Set by a media error handler to force a remount with fresh URLs; cleared
 		// once the remount happens.
 		let forceRemount = false;
 		let lastMediaRecoveryAt = 0;
+		// Media failure bookkeeping: the first error for a wallpaper may just be a
+		// stale token (fixed by a refresh+remount); a SECOND error for the same id
+		// means the bytes themselves are unusable (e.g. an mkv/avi Chromium cannot
+		// decode) — demote it to its preview image instead of looping forever.
+		const mediaFailures = new Map(); // wallpaperId → consecutive failure count
+		const demotedToPreview = new Set(); // wallpaperIds now rendered as stills
 
 		function buildMedia(sel) {
 		  let media;
@@ -617,7 +649,7 @@ window.__ModuleLoader__.load({
 		    media.setAttribute("referrerpolicy", "no-referrer");
 		    media.setAttribute("frameborder", "0");
 		    media.setAttribute("scrolling", "no");
-		    media.setAttribute("title", "Wallpaper Engine web wallpaper");
+		    media.setAttribute("title", S().iframeTitle);
 		    media.className = "webg-media webg-iframe";
 		  } else {
 		    // Static wallpaper: the scene/application preview as a still image.
@@ -628,22 +660,45 @@ window.__ModuleLoader__.load({
 		    media.setAttribute("decoding", "async");
 		    media.className = "webg-media";
 		  }
-		  // Self-heal: if the media fails to load (e.g. its token died on an
-		  // inventory rebuild), refetch fresh URLs and remount — throttled to once
-		  // per 10 s so a permanently-broken wallpaper cannot loop.
 		  media.addEventListener("error", () => {
-		    const now = Date.now();
-		    if (now - lastMediaRecoveryAt < 10000) return;
-		    lastMediaRecoveryAt = now;
-		    forceRemount = true;
-		    loadInventory(true);
+		    const id = sel.id;
+		    const count = (mediaFailures.get(id) || 0) + 1;
+		    mediaFailures.set(id, count);
+		    const w = selection.inventory.wallpapers.find((x) => x.id === id);
+		    if (count === 1) {
+		      // Maybe just a dead token: refetch fresh URLs and remount (throttled).
+		      const now = Date.now();
+		      if (now - lastMediaRecoveryAt < 10000) return;
+		      lastMediaRecoveryAt = now;
+		      forceRemount = true;
+		      loadInventory(true);
+		    } else if (w && w.preview && !demotedToPreview.has(id)) {
+		      // The media itself is unusable here — fall back to the still preview.
+		      demotedToPreview.add(id);
+		      applySelection(id);
+		    }
 		  });
 		  return media;
 		}
 
+		// Crossfade/clear leave timers: tracked so dispose can cancel them instead of
+		// letting them fire on torn-down nodes afterwards.
+		const pendingTimers = new Set();
+		function schedule(fn, ms) {
+		  if (typeof window === "undefined" || typeof window.setTimeout !== "function") {
+		    fn();
+		    return null;
+		  }
+		  const token = window.setTimeout(() => {
+		    pendingTimers.delete(token);
+		    fn();
+		  }, ms);
+		  pendingTimers.add(token);
+		  return token;
+		}
+
 		function syncLayers() {
 		  const existing = document.getElementById(LAYER_ID);
-		  const hasTimeout = typeof window !== "undefined" && typeof window.setTimeout === "function";
 
 		  if (selection.url) {
 		    // Key by wallpaper id, NOT by media URL: inventory rebuilds re-mint
@@ -670,8 +725,7 @@ window.__ModuleLoader__.load({
 		      if (existing) {
 		        existing.classList.add("webg-layer--leave");
 		        const stale = existing;
-		        if (hasTimeout) window.setTimeout(() => stale.remove(), CROSSFADE_MS + 120);
-		        else stale.remove();
+		        schedule(() => stale.remove(), CROSSFADE_MS + 120);
 		      }
 		    }
 		    const node = document.getElementById(LAYER_ID);
@@ -686,16 +740,14 @@ window.__ModuleLoader__.load({
 		    existing.removeAttribute("id");
 		    existing.classList.add("webg-layer--leave");
 		    const stale = existing;
-		    const finish = () => {
+		    schedule(() => {
 		      stale.remove();
 		      if (!document.getElementById(LAYER_ID)) {
 		        const s = document.getElementById(SCRIM_ID);
 		        if (s) s.remove();
 		        document.body.removeAttribute(ACTIVE_ATTR);
 		      }
-		    };
-		    if (hasTimeout) window.setTimeout(finish, CROSSFADE_MS + 120);
-		    else finish();
+		    }, CROSSFADE_MS + 120);
 		  }
 
 		  // Scrim: present while a wallpaper is active. On clear it outlives the
@@ -722,8 +774,9 @@ window.__ModuleLoader__.load({
 		  s.setProperty("--webg-saturate", String(1.15 + selection.blur * 0.028));
 		  s.setProperty("--webg-glass-brightness", "1.04");
 		  s.setProperty("--webg-wallpaper-blur", selection.wallpaperBlur + "px");
-		  // Scaling compensates the transparent fringe CSS blur reveals at edges.
-		  s.setProperty("--webg-wallpaper-scale", (1 + selection.wallpaperBlur * 0.006).toFixed(4));
+		  // Dither-noise strength scales with blur: invisible at 0, ~4% at 60px.
+		  s.setProperty("--webg-noise-opacity",
+		    selection.wallpaperBlur > 0 ? (0.02 + selection.wallpaperBlur * 0.0004).toFixed(4) : "0");
 		  // Canvas fit: object-fit/position for video and still wallpapers (iframes
 		  // ignore object-fit — web wallpapers always fill their layer).
 		  s.setProperty("--webg-fit", selection.fit);
@@ -746,7 +799,7 @@ window.__ModuleLoader__.load({
 		  s.removeProperty("--webg-saturate");
 		  s.removeProperty("--webg-glass-brightness");
 		  s.removeProperty("--webg-wallpaper-blur");
-		  s.removeProperty("--webg-wallpaper-scale");
+		  s.removeProperty("--webg-noise-opacity");
 		  s.removeProperty("--webg-fit");
 		  s.removeProperty("--webg-position");
 		  const scrim = document.getElementById(SCRIM_ID);
@@ -755,16 +808,28 @@ window.__ModuleLoader__.load({
 
 		// ── Settings picker ─────────────────────────────────────────────────────────
 		function SliderRow(label, min, max, step, value, onInput, suffix) {
-		  return React.createElement("div", { className: "webg-row webg-slider-row" },
+		  // A Fragment of three cells — the surrounding .webg-effects grid keeps
+		  // every slider starting and ending at the same x regardless of how wide
+		  // the label text is (壁纸模糊 vs 暗化 vs Wallpaper blur…).
+		  // --webg-p feeds the filled-track gradient; updated inline while dragging
+		  // so the fill tracks the thumb even between re-renders.
+		  const pct = ((value - min) / (max - min)) * 100;
+		  const set = (e) => {
+		    const v = Number(e.target.value);
+		    if (e.target.style && typeof e.target.style.setProperty === "function") {
+		      e.target.style.setProperty("--webg-p", String(((v - min) / (max - min)) * 100));
+		    }
+		    onInput(v);
+		  };
+		  return React.createElement(React.Fragment, null,
 		    React.createElement("span", { className: "webg-hint webg-label" }, label),
 		    React.createElement("input", {
 		      className: "webg-slider", type: "range",
 		      min: String(min), max: String(max), step: String(step),
 		      value: String(value),
-		      // onInput fires continuously while dragging (onChange may wait for
-		      // release) — that is what makes the visual feedback instant.
-		      onInput: (e) => onInput(Number(e.target.value)),
-		      onChange: (e) => onInput(Number(e.target.value)),
+		      style: { "--webg-p": String(pct) },
+		      onInput: set,
+		      onChange: set,
 		    }),
 		    React.createElement("span", { className: "webg-hint webg-value" }, suffix),
 		  );
@@ -808,7 +873,13 @@ window.__ModuleLoader__.load({
 		  const t = S();
 		  const onTogglePlay = () => { selection.playing = !selection.playing; emit(); };
 		  const onClear = () => applySelection("");
-		  const onRefresh = () => loadInventory(true);
+		  const onRefresh = () => {
+		    // A manual refresh also retries wallpapers previously demoted to their
+		    // preview after decode failures.
+		    demotedToPreview.clear();
+		    mediaFailures.clear();
+		    loadInventory(true);
+		  };
 		  const onLangChange = (e) => {
 		    selection.lang = e.target.value;
 		    persistSelection();
@@ -828,15 +899,12 @@ window.__ModuleLoader__.load({
 		  };
 		  const onToggleRotation = () => {
 		    selection.rotationEnabled = !selection.rotationEnabled;
-		    if (selection.rotationEnabled) {
-		      if (!selection.rotationGroupId) {
-		        const usable = firstUsableGroup();
-		        if (usable) selection.rotationGroupId = usable.id;
-		      }
-		      if (!rotationCandidates().some((w) => w.id === selection.id)) {
-		        const first = rotationCandidates()[0];
-		        if (first) { applySelection(first.id); return; }
-		      }
+		    // The checkbox is disabled without a usable group, so a group id always
+		    // exists here when enabling.
+		    if (selection.rotationEnabled &&
+		        !rotationCandidates().some((w) => w.id === selection.id)) {
+		      const first = rotationCandidates()[0];
+		      if (first) { applySelection(first.id); return; }
 		    }
 		    persistSelection();
 		    syncRotationTimer();
@@ -860,13 +928,22 @@ window.__ModuleLoader__.load({
 		  };
 		  const onTogglePauseOnHidden = () => {
 		    selection.pauseOnHidden = !selection.pauseOnHidden;
-		    if (!selection.pauseOnHidden) setAutoPause("hidden", false);
+		    if (selection.pauseOnHidden) {
+		      // Re-enabling while already hidden must re-apply the reason — the
+		      // visibilitychange listener only fires on CHANGES.
+		      if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+		        setAutoPause("hidden", true);
+		      }
+		    } else {
+		      setAutoPause("hidden", false);
+		    }
 		    persistSelection();
 		    emit();
 		  };
 		  const onTogglePauseOnBattery = () => {
 		    selection.pauseOnBattery = !selection.pauseOnBattery;
-		    if (!selection.pauseOnBattery) setAutoPause("battery", false);
+		    if (selection.pauseOnBattery) applyBatteryPause(); // re-evaluate NOW
+		    else setAutoPause("battery", false);
 		    persistSelection();
 		    emit();
 		  };
@@ -1144,10 +1221,12 @@ window.__ModuleLoader__.load({
 		          React.createElement("option", { key: POSITIONS[i], value: POSITIONS[i] }, label),
 		        )),
 		      ),
-		      SliderRow(t.wallpaperBlur, 0, 60, 1, sel.wallpaperBlur, onWallpaperBlur, sel.wallpaperBlur + "px"),
-		      SliderRow(t.scrim, 0, 90, 5, Math.round(sel.scrim * 100), onScrim, Math.round(sel.scrim * 100) + "%"),
-		      SliderRow(t.border, 0, 90, 5, Math.round(sel.border * 100), onBorder, Math.round(sel.border * 100) + "%"),
-		      SliderRow(t.glass, 0, 40, 1, sel.blur, onBlur, sel.blur + "px"),
+		      React.createElement("div", { className: "webg-effects" },
+		        SliderRow(t.wallpaperBlur, 0, 60, 1, sel.wallpaperBlur, onWallpaperBlur, sel.wallpaperBlur + "px"),
+		        SliderRow(t.scrim, 0, 90, 5, Math.round(sel.scrim * 100), onScrim, Math.round(sel.scrim * 100) + "%"),
+		        SliderRow(t.border, 0, 90, 5, Math.round(sel.border * 100), onBorder, Math.round(sel.border * 100) + "%"),
+		        SliderRow(t.glass, 0, 40, 1, sel.blur, onBlur, sel.blur + "px"),
+		      ),
 		    ),
 		    // ── Resource monitor ──
 		    sel.id && React.createElement("div", { className: "webg-row webg-monitor-row" },
@@ -1181,6 +1260,7 @@ window.__ModuleLoader__.load({
 		          : t.statusUsable(usableList.length)) +
 		        (sel.rotationEnabled ? " · " + t.autoRotating : "") +
 		        (autoPaused ? " · " + t.autoPaused : "") +
+		        (sel.id && demotedToPreview.has(sel.id) ? " · " + t.decodeFallback : "") +
 		        (sel.inventory.installDir ? " · " + sel.inventory.installDir : "")),
 		    ),
 		  );
@@ -1198,14 +1278,35 @@ window.__ModuleLoader__.load({
 		  }
 		  .webg-layer--enter { opacity: 0; }
 		  .webg-layer--leave { opacity: 0; }
+		  /* Overscan: the media is LARGER than the layer by one blur radius on every
+		     side, so the transparent fringe CSS blur produces is clipped by the
+		     layer's overflow:hidden instead of compensated with a content-warping
+		     scale. 1× is the fringe a Gaussian kernel actually needs; more would
+		     double GPU fill and mis-anchor non-center object-positions. A slight
+		     saturate keeps blurred colours from washing out. */
 		  .webg-layer .webg-media {
-		    width: 100%; height: 100%; object-fit: var(--webg-fit, cover);
+		    position: absolute;
+		    inset: calc(-1 * var(--webg-wallpaper-blur, 0px));
+		    width: calc(100% + 2 * var(--webg-wallpaper-blur, 0px));
+		    height: calc(100% + 2 * var(--webg-wallpaper-blur, 0px));
+		    max-width: none; max-height: none;
+		    object-fit: var(--webg-fit, cover);
 		    object-position: var(--webg-position, center);
 		    display: block;
 		    background: transparent; border: 0;
-		    filter: blur(var(--webg-wallpaper-blur, 0px));
-		    transform: scale(var(--webg-wallpaper-scale, 1));
-		    transform-origin: center;
+		    filter: blur(var(--webg-wallpaper-blur, 0px)) saturate(1.08);
+		  }
+
+		  /* Gaussian blur alone shows banding on smooth gradients; a whisper of
+		     fractal noise over the layer dithers it away (iOS does the same inside
+		     its frosted materials). Opacity rides the blur radius — zero blur, zero
+		     noise. */
+		  .webg-layer::after {
+		    content: ""; position: absolute; inset: 0; pointer-events: none;
+		    opacity: var(--webg-noise-opacity, 0);
+		    background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120"><filter id="n"><feTurbulence type="fractalNoise" baseFrequency="0.9" numOctaves="2" stitchTiles="stitch"/></filter><rect width="120" height="120" filter="url(%23n)"/></svg>');
+		    background-size: 120px 120px;
+		    mix-blend-mode: overlay;
 		  }
 
 		  /* Scrim: above the wallpaper (-1 > -2), below the UI. */
@@ -1272,7 +1373,7 @@ window.__ModuleLoader__.load({
 		    font-size: 13px;
 		    color: var(--dsw-alias-state-error-primary, #d44);
 		  }
-		  .webg-label { min-width: 28px; }
+		  .webg-label { white-space: nowrap; }
 		  .webg-value { min-width: 42px; text-align: right; font-variant-numeric: tabular-nums; }
 
 		  .webg-btn {
@@ -1305,13 +1406,33 @@ window.__ModuleLoader__.load({
 		  }
 
 		  .webg-select, .webg-text {
-		    padding: 4px 8px;
-		    border-radius: 6px;
+		    padding: 5px 10px;
+		    border-radius: 8px;
 		    border: 1px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.35));
 		    background: var(--dsw-alias-bg-layer-1, rgba(128, 128, 128, 0.12));
 		    color: var(--dsw-alias-label-primary, inherit);
 		    font-size: 13px;
+		    transition: border-color 120ms ease, background-color 120ms ease;
 		  }
+		  /* Custom select: drop the OS chrome, draw our own chevron (mid-gray reads
+		     on both light and dark themes), roomier hit area, shell-style focus. */
+		  .webg-select {
+		    -webkit-appearance: none;
+		    appearance: none;
+		    padding-right: 28px;
+		    cursor: pointer;
+		    background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" width="10" height="6" viewBox="0 0 10 6"><path d="M1 1l4 4 4-4" fill="none" stroke="%23888" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>');
+		    background-repeat: no-repeat;
+		    background-position: right 10px center;
+		  }
+		  .webg-select:hover:not(:disabled), .webg-text:hover:not(:disabled) {
+		    border-color: var(--dsw-alias-border-l1, rgba(128, 128, 128, 0.5));
+		  }
+		  .webg-select:focus-visible, .webg-text:focus-visible {
+		    outline: 2px solid var(--dsw-alias-brand-primary, rgb(15, 17, 21));
+		    outline-offset: 1px;
+		  }
+		  .webg-select:disabled { opacity: 0.45; cursor: not-allowed; }
 		  .webg-text { flex: 1; min-width: 0; }
 		  .webg-search { max-width: 320px; }
 		  .webg-lang { display: inline-flex; align-items: center; gap: 6px; margin-left: auto; }
@@ -1323,8 +1444,43 @@ window.__ModuleLoader__.load({
 		    font-size: 13px; cursor: pointer;
 		  }
 
-		  .webg-slider { flex: 1; accent-color: var(--dsw-alias-brand-primary, rgb(15, 17, 21)); }
-		  .webg-slider-row { display: flex; align-items: center; gap: 8px; }
+		  /* Custom range slider (Chromium): slim filled track + ringed thumb instead
+		     of the default chunky control. --webg-p (0–100) drives the fill. */
+		  .webg-slider {
+		    -webkit-appearance: none;
+		    appearance: none;
+		    width: 100%; height: 22px; margin: 0;
+		    background: transparent; cursor: pointer;
+		  }
+		  .webg-slider::-webkit-slider-runnable-track {
+		    height: 4px; border-radius: 2px;
+		    background: linear-gradient(to right,
+		      var(--dsw-alias-brand-primary, rgb(15, 17, 21)) 0%,
+		      var(--dsw-alias-brand-primary, rgb(15, 17, 21)) calc(var(--webg-p, 0) * 1%),
+		      var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.35)) calc(var(--webg-p, 0) * 1%));
+		  }
+		  .webg-slider::-webkit-slider-thumb {
+		    -webkit-appearance: none;
+		    width: 14px; height: 14px; border-radius: 50%;
+		    margin-top: -5px; /* centers the 14px thumb on the 4px track */
+		    background: var(--dsw-alias-brand-primary-invert, rgb(249, 250, 251));
+		    border: 2.5px solid var(--dsw-alias-brand-primary, rgb(15, 17, 21));
+		    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.28);
+		    transition: transform 120ms ease;
+		  }
+		  .webg-slider:hover::-webkit-slider-thumb,
+		  .webg-slider:focus-visible::-webkit-slider-thumb { transform: scale(1.18); }
+		  .webg-slider:focus-visible { outline: none; }
+		  /* Effects grid: one shared grid across all slider rows, so every slider
+		     starts and ends at the same x no matter how wide its label is. */
+		  .webg-effects {
+		    display: grid;
+		    grid-template-columns: max-content 1fr 3.2em;
+		    gap: 8px 10px;
+		    align-items: center;
+		  }
+		  .webg-effects .webg-label { white-space: nowrap; }
+		  .webg-effects .webg-value { text-align: right; }
 
 		  .webg-monitor-row { gap: 14px; }
 		  .webg-fps { font-variant-numeric: tabular-nums; }
@@ -1460,6 +1616,14 @@ window.__ModuleLoader__.load({
 		        unsubLayers();
 		        unsubEffects();
 		        clearRotationTimer();
+		        // Cancel pending crossfade/clear timers so they never fire on
+		        // torn-down nodes after dispose.
+		        for (const token of [...pendingTimers]) {
+		          if (typeof window !== "undefined" && typeof window.clearTimeout === "function") {
+		            window.clearTimeout(token);
+		          }
+		        }
+		        pendingTimers.clear();
 		        // Remove EVERY layer instance (a crossfade-leaving layer has no id).
 		        const doomed = document.querySelectorAll(".webg-layer");
 		        for (const node of [...doomed]) node.remove();
@@ -1493,8 +1657,9 @@ window.__ModuleLoader__.load({
 		      let battery = null;
 		      let cancelled = false;
 		      const update = () => {
-		        if (!battery || !selection.pauseOnBattery) return;
-		        setAutoPause("battery", !battery.charging && battery.level <= BATTERY_SAVER_LEVEL);
+		        if (!battery) return;
+		        batteryState = { charging: battery.charging, level: battery.level };
+		        applyBatteryPause();
 		      };
 		      navigator.getBattery().then((b) => {
 		        if (cancelled) return;
@@ -1509,6 +1674,7 @@ window.__ModuleLoader__.load({
 		          battery.removeEventListener("chargingchange", update);
 		          battery.removeEventListener("levelchange", update);
 		        }
+		        batteryState = null;
 		        setAutoPause("battery", false);
 		      };
 		    });

package/lib/core.js

@@ -191,11 +191,13 @@ export function weBinaryName(platform = process.platform) {
 
 /**
  * First candidate directory that contains the WE binary, in order.
+ * Async: io methods may be sync or return promises (the host injects
+ * fs/promises so discovery never blocks the event loop).
  * @param {string[]} candidates
- * @param {{ existsSync?: (p: string) => boolean, platform?: string }} [io]
- * @returns {string | null}
+ * @param {{ existsSync?: (p: string) => boolean | Promise<boolean>, platform?: string }} [io]
+ * @returns {Promise<string | null>}
  */
-export function findInstallDir(candidates, io = {}) {
+export async function findInstallDir(candidates, io = {}) {
   const exists = io.existsSync || existsSync;
   const bin = weBinaryName(io.platform || process.platform);
   const seen = new Set();
@@ -204,7 +206,7 @@ export function findInstallDir(candidates, io = {}) {
     const dir = normalize(String(raw));
     if (seen.has(dir)) continue;
     seen.add(dir);
-    if (exists(join(dir, bin))) return dir;
+    if (await exists(join(dir, bin))) return dir;
   }
   return null;
 }
@@ -237,15 +239,15 @@ export function installDirCandidates(input = {}) {
  * libraryfolders.vdf, so it must be recovered by direct inspection).
  * @param {string[]} probes
  * @param {string[]} vdfLibraries
- * @param {{ existsSync?: (p: string) => boolean, platform?: string }} [io]
- * @returns {string[]}
+ * @param {{ existsSync?: (p: string) => boolean | Promise<boolean>, platform?: string }} [io]
+ * @returns {Promise<string[]>}
  */
-export function workshopLibraryRoots(probes, vdfLibraries, io = {}) {
+export async function workshopLibraryRoots(probes, vdfLibraries, io = {}) {
   const exists = io.existsSync || existsSync;
   const bin = weBinaryName(io.platform || process.platform);
   const libs = [...vdfLibraries];
   for (const probe of probes) {
-    if (exists(join(probe, 'steamapps', 'common', 'wallpaper_engine', bin))) {
+    if (await exists(join(probe, 'steamapps', 'common', 'wallpaper_engine', bin))) {
       libs.push(probe);
     }
   }
@@ -298,18 +300,20 @@ export function isInsideDir(root, target, platform = process.platform) {
  * server at arbitrary files.
  *
  * @param {string} dir
- * @param {{ readFileSync?: (p: string, e: string) => string, existsSync?: (p: string) => boolean }} [io]
+ * @param {{ readFileSync?: (p: string, e: string) => string | Promise<string>, existsSync?: (p: string) => boolean | Promise<boolean> }} [io]
  */
-export function readProject(dir, io = {}) {
+export async function readProject(dir, io = {}) {
   const read = io.readFileSync || readFileSync;
   const exists = io.existsSync || existsSync;
   const pj = join(dir, 'project.json');
-  if (!exists(pj)) return null;
+  if (!await exists(pj)) return null;
   try {
-    const o = JSON.parse(read(pj, 'utf8'));
+    const o = JSON.parse(await read(pj, 'utf8'));
     if (!o || typeof o !== 'object' || typeof o.file !== 'string' || !o.file.trim()) return null;
-    let type = typeof o.type === 'string' ? o.type.toLowerCase() : inferType(o.file);
-    if (!KINDS.includes(type)) type = 'scene';
+    // A declared-but-unknown type (typo, trailing whitespace) is not
+    // evidence of "scene": fall back to extension inference first.
+    let type = typeof o.type === 'string' ? o.type.trim().toLowerCase() : '';
+    if (!KINDS.includes(type)) type = inferType(o.file);
     const fileAbs = resolve(dir, o.file);
     if (!isInsideDir(dir, fileAbs)) return null;
     let previewAbs = null;
@@ -334,19 +338,19 @@ export function readProject(dir, io = {}) {
  * Enumerate every wallpaper project under the given roots (first occurrence
  * of an id wins), sorted case-insensitively by title.
  * @param {string[]} roots
- * @param {{ readdirSync?: (p: string) => string[], statSync?: (p: string) => { isDirectory(): boolean } }} [io]
+ * @param {{ readdirSync?: (p: string) => string[] | Promise<string[]>, statSync?: (p: string) => { isDirectory(): boolean } | Promise<{ isDirectory(): boolean }> }} [io]
  */
-export function enumerateWallpapers(roots, io = {}) {
+export async function enumerateWallpapers(roots, io = {}) {
   const readdir = io.readdirSync || readdirSync;
   const stat = io.statSync || statSync;
   const found = new Map();
   for (const root of roots) {
     let entries;
-    try { entries = readdir(root); } catch { continue; }
+    try { entries = await readdir(root); } catch { continue; }
     for (const entry of entries) {
       const dir = join(root, entry);
-      try { if (!stat(dir).isDirectory()) continue; } catch { continue; }
-      const proj = readProject(dir, io);
+      try { if (!(await stat(dir)).isDirectory()) continue; } catch { continue; }
+      const proj = await readProject(dir, io);
       if (!proj || found.has(proj.id)) continue;
       found.set(proj.id, proj);
     }
@@ -360,21 +364,21 @@ export function enumerateWallpapers(roots, io = {}) {
  * plus the workshop content folder of every owning library.
  * @param {string | null} installDir
  * @param {string[]} libraryRoots
- * @param {{ existsSync?: (p: string) => boolean }} [io]
- * @returns {string[]}
+ * @param {{ existsSync?: (p: string) => boolean | Promise<boolean> }} [io]
+ * @returns {Promise<string[]>}
  */
-export function wallpaperRoots(installDir, libraryRoots, io = {}) {
+export async function wallpaperRoots(installDir, libraryRoots, io = {}) {
   const exists = io.existsSync || existsSync;
   const roots = [];
   if (installDir) {
     for (const sub of ['defaultprojects', 'myprojects']) {
       const p = join(installDir, 'projects', sub);
-      if (exists(p)) roots.push(p);
+      if (await exists(p)) roots.push(p);
     }
   }
   for (const lib of libraryRoots) {
     const ws = join(lib, 'steamapps', 'workshop', 'content', WE_APPID);
-    if (exists(ws)) roots.push(ws);
+    if (await exists(ws)) roots.push(ws);
   }
   return roots;
 }
@@ -463,30 +467,36 @@ export function resolvePlaylistItem(item, byPath, byId) {
 /**
  * Parse an HTTP Range header for a resource of `size` bytes.
  * Supports `bytes=a-b`, `bytes=a-`, `bytes=-suffix`.
+ *
+ * RFC 9110 §14.2: a server MUST ignore a Range header it does not understand
+ * (malformed, wrong unit, multi-range) and answer 200 — 416 is reserved for
+ * syntactically valid but unsatisfiable ranges.
+ *
  * @returns {null | { start: number, end: number } | { error: true }}
- *   null    → no/empty header, serve the whole body (200)
- *   error   → unsatisfiable or malformed, answer 416
+ *   null    → no header, or an invalid/unsupported one: ignore it, serve 200
+ *   error   → valid syntax but unsatisfiable for this resource: answer 416
  *   start/end → inclusive byte range, answer 206
  */
 export function parseRangeHeader(header, size) {
   if (!header || typeof header !== 'string') return null;
   if (!Number.isFinite(size) || size < 0) return { error: true };
   const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
-  if (!m) return { error: true };
+  if (!m) return null; // wrong unit / multi-range / garbage → ignore (200)
   const [, a, b] = m;
-  if (a === '' && b === '') return { error: true };
+  if (a === '' && b === '') return null; // "bytes=-" is not a range → 200
   let start;
   let end;
   if (a === '') {
     const suffix = parseInt(b, 10);
-    if (!Number.isFinite(suffix) || suffix <= 0) return { error: true };
+    if (!Number.isFinite(suffix) || suffix <= 0) return null; // "bytes=-0"
     start = Math.max(0, size - suffix);
     end = size - 1;
   } else {
     start = parseInt(a, 10);
     end = b === '' ? size - 1 : Math.min(parseInt(b, 10), size - 1);
   }
-  if (!Number.isFinite(start) || !Number.isFinite(end)) return { error: true };
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+  // Valid syntax; unsatisfiable for this resource.
   if (size === 0 || start > end || start >= size) return { error: true };
   return { start, end };
 }
@@ -517,13 +527,16 @@ export function mimeFor(absPath) {
  *
  * @param {{ installDir: string | null, libraryRoots: string[] }} discovery
  * @param {object} [io] overridable IO: existsSync/readFileSync/readdirSync/
- *   statSync (default to node:fs), plus:
- *   - `mint(entry)` — mint a media/preview token for a file entry; the host
- *     provides a random-token map, tests provide a spy.
+ *   statSync (default to node:fs sync functions; each may also return a
+ *   promise — the host injects fs/promises to keep the event loop free),
+ *   plus:
+ *   - `mint(entry)` — mint a media/preview token for a file entry; when it
+ *     returns a falsy value (or is omitted) the URL is null, never
+ *     "…/media/null".
  *   - `base` — URL prefix for media/preview links (default '/we-background').
- * @returns {{ installDir, total, portableCount, wallpapers, playlists }}
+ * @returns {Promise<{ installDir, total, portableCount, wallpapers, playlists }>}
  */
-export function buildInventoryFrom(discovery = {}, io = {}) {
+export async function buildInventoryFrom(discovery = {}, io = {}) {
   const exists = io.existsSync || existsSync;
   const read = io.readFileSync || readFileSync;
   const mint = io.mint || (() => null);
@@ -531,35 +544,38 @@ export function buildInventoryFrom(discovery = {}, io = {}) {
 
   const installDir = discovery.installDir || null;
   const libraryRoots = Array.isArray(discovery.libraryRoots) ? discovery.libraryRoots : [];
-  const roots = wallpaperRoots(installDir, libraryRoots, { existsSync: exists });
-  const projects = enumerateWallpapers(roots, io);
+  const roots = await wallpaperRoots(installDir, libraryRoots, { existsSync: exists });
+  const projects = await enumerateWallpapers(roots, io);
   const byId = new Map(projects.map((p) => [p.id, p]));
   const byPath = new Map(projects.map((p) => [pathKey(p.fileAbs), p.id]));
 
-  const wallpapers = projects.map((p) => {
+  const wallpapers = [];
+  for (const p of projects) {
     const portable = PORTABLE_KINDS.includes(p.type);
-    const hasMedia = portable && exists(p.fileAbs);
-    const hasPreview = Boolean(p.previewAbs) && exists(p.previewAbs);
-    return {
+    const hasMedia = portable && await exists(p.fileAbs);
+    const hasPreview = Boolean(p.previewAbs) && await exists(p.previewAbs);
+    const mediaToken = hasMedia
+      ? mint({ abs: p.fileAbs, rootDir: p.type === 'web' ? p.dir : null, key: `${p.id}:media` })
+      : null;
+    const previewToken = hasPreview
+      ? mint({ abs: p.previewAbs, rootDir: null, key: `${p.id}:preview` })
+      : null;
+    wallpapers.push({
       id: p.id,
       title: p.title,
       type: p.type,
-      playable: hasMedia,
-      media: hasMedia
-        ? `${base}/media/${mint({ abs: p.fileAbs, rootDir: p.type === 'web' ? p.dir : null })}`
-        : null,
-      preview: hasPreview
-        ? `${base}/preview/${mint({ abs: p.previewAbs, rootDir: null })}`
-        : null,
-    };
-  });
+      playable: hasMedia && Boolean(mediaToken),
+      media: hasMedia && mediaToken ? `${base}/media/${mediaToken}` : null,
+      preview: hasPreview && previewToken ? `${base}/preview/${previewToken}` : null,
+    });
+  }
   const playableIds = new Set(wallpapers.filter((w) => w.playable).map((w) => w.id));
 
   let playlists = [];
   const configPath = installDir ? join(installDir, 'config.json') : null;
-  if (configPath && exists(configPath)) {
+  if (configPath && await exists(configPath)) {
     try {
-      playlists = parsePlaylists(JSON.parse(read(configPath, 'utf8')));
+      playlists = parsePlaylists(JSON.parse(await read(configPath, 'utf8')));
     } catch { /* malformed config.json → no playlists, not fatal */ }
   }
   const playlistView = playlists.map((playlist, index) => {

package/lib/index.js

@@ -6,17 +6,21 @@
  * All parsing/enumeration logic lives in the pure layer (lib/core.js); this
  * file only wires it into same-origin HTTP routes on `ctx.webServer`:
  *
- *   GET  /we-background/inventory[?refresh=1] → { installDir, wallpapers, playlists }
+ *   GET  /we-background/inventory[?refresh=1] → { installDir, total,
+ *         portableCount, wallpapers, playlists }
  *   GET  /we-background/media/<token>[/<sub-asset>…] → video / web HTML + assets
  *   GET  /we-background/preview/<token>             → preview image
  *
  * Security model
- *   - Tokens are 72-bit random values minted per inventory build (not
- *     reversible encodings of paths). Knowing a filesystem path grants
- *     nothing; only files enumerated into the inventory are reachable.
- *     Rebuilding the inventory re-mints every token, so stale URLs die.
+ *   - Tokens are 72-bit random values (not reversible encodings of paths).
+ *     Knowing a filesystem path grants nothing; only files enumerated into
+ *     the inventory are reachable. Tokens are stable per wallpaper across
+ *     TTL-triggered rebuilds (so an in-flight video stream is never killed
+ *     by a background refresh) and re-minted on an explicit ?refresh=1, so
+ *     deliberately stale URLs die.
  *   - Web-wallpaper sub-assets resolve strictly INSIDE their project
- *     directory (core.isInsideDir) — `..` traversal is answered 403.
+ *     directory (core.isInsideDir) — `..` and backslash traversal are
+ *     answered 403.
  *   - project.json-declared files must also be inside the project directory
  *     (core.readProject), so a hostile workshop item cannot point the server
  *     at arbitrary files.
@@ -26,6 +30,9 @@
  *   - Everything is loopback same-origin; `X-Content-Type-Options: nosniff`
  *     on every media response.
  *
+ * Async: discovery (reg.exe, vdf scan) and inventory builds run through
+ * fs/promises, so a rebuild never blocks the event loop mid-stream.
+ *
  * Lifecycle: every route registers through the plugin fiber and unwinds on
  * unload; the inventory cache and token map are dropped with it. The plugin
  * contributes no model-visible tool and no prompt text.
@@ -33,11 +40,9 @@
 
 import {
   createReadStream,
-  existsSync,
-  readFileSync,
-  statSync,
+  promises as fsp,
 } from 'node:fs';
-import { execFileSync } from 'node:child_process';
+import { execFile } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { join } from 'node:path';
 
@@ -47,133 +52,197 @@ import * as core from './core.js';
 const BASE = '/we-background';
 /** Inventory is cached and rebuilt at most this often unless ?refresh=1. */
 const INVENTORY_TTL_MS = 30_000;
+/** Steam layout barely moves; re-discover at most this often on TTL builds. */
+const DISCOVERY_TTL_MS = 10 * 60_000;
+
+/** fs/promises-backed io for the pure layer (awaited there). */
+const asyncIo = {
+  existsSync: async (p) => { try { await fsp.access(p); return true; } catch { return false; } },
+  readFileSync: (p, encoding) => fsp.readFile(p, encoding),
+  readdirSync: (p) => fsp.readdir(p),
+  statSync: (p) => fsp.stat(p),
+};
 
 /** Steam root recorded by the Windows installer; null elsewhere/on failure. */
 function steamRegistryRoot() {
-  if (process.platform !== 'win32') return null;
-  try {
+  if (process.platform !== 'win32') return Promise.resolve(null);
+  return new Promise((resolvePromise) => {
     const reg = join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'reg.exe');
-    const out = execFileSync(
+    execFile(
       reg,
       ['query', 'HKCU\\Software\\Valve\\Steam', '/v', 'SteamPath'],
-      { encoding: 'utf8', windowsHide: true, timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] },
+      { encoding: 'utf8', windowsHide: true, timeout: 5000 },
+      (err, stdout) => {
+        if (err) { resolvePromise(null); return; }
+        resolvePromise(core.steamPathFromRegQuery(stdout));
+      },
     );
-    return core.steamPathFromRegQuery(out);
-  } catch {
-    return null;
-  }
+  });
 }
 
 /** Full discovery pass: install dir + every library owning WE content. */
-function discover() {
+async function discover() {
   const probes = core.steamProbeDirs();
-  const registryRoot = steamRegistryRoot();
+  const registryRoot = await steamRegistryRoot();
   const searchRoots = registryRoot ? [registryRoot, ...probes] : probes;
   const vdfLibraries = [];
   for (const root of searchRoots) {
     const vdf = join(root, 'steamapps', 'libraryfolders.vdf');
-    if (!existsSync(vdf)) continue;
+    if (!await asyncIo.existsSync(vdf)) continue;
     try {
-      vdfLibraries.push(...core.librariesFromVdfText(readFileSync(vdf, 'utf8')));
+      vdfLibraries.push(...core.librariesFromVdfText(await asyncIo.readFileSync(vdf, 'utf8')));
     } catch { /* unreadable vdf → skip this root */ }
   }
-  const installDir = core.findInstallDir(
+  const installDir = await core.findInstallDir(
     core.installDirCandidates({ registryRoot, libraryRoots: vdfLibraries }),
+    asyncIo,
   );
-  const libraryRoots = core.workshopLibraryRoots(searchRoots, vdfLibraries);
+  const libraryRoots = await core.workshopLibraryRoots(searchRoots, vdfLibraries, asyncIo);
   return { installDir, libraryRoots };
 }
 
-export const inject = ['webServer'];
-
-export function apply(ctx) {
-  const webServer = ctx.webServer;
-  if (!webServer || typeof webServer.register !== 'function') {
-    return () => {}; // defensive: inject guarantees the service in practice
-  }
+/**
+ * Register all routes on a webServer-like registry and return a disposer.
+ * Extracted from apply() so integration tests can drive the HTTP surface
+ * against a fixture discovery without a live Steam install.
+ *
+ * @param {{ register(route: { kind: 'exact'|'prefix', path: string, handler: Function }): () => void }} webServer
+ * @param {{ discover?: () => Promise<{ installDir: string|null, libraryRoots: string[] }>, inventoryTtlMs?: number, discoveryTtlMs?: number }} [opts]
+ */
+export function createRouteRegistrar(webServer, opts = {}) {
+  const discoverFn = opts.discover || discover;
+  const inventoryTtlMs = opts.inventoryTtlMs ?? INVENTORY_TTL_MS;
+  const discoveryTtlMs = opts.discoveryTtlMs ?? DISCOVERY_TTL_MS;
 
   // ── Token registry ──────────────────────────────────────────────────────
-  // token → { abs, rootDir|null }. rootDir is set for renderable projects so
-  // web wallpapers can fetch their bundled sub-assets (contained, see below).
+  // token → { abs, rootDir|null }. rootDir is set for renderable web projects
+  // so their bundled sub-assets can be fetched (contained, see below).
+  // Tokens are keyed per wallpaper asset (`<id>:media` / `<id>:preview`):
+  // TTL rebuilds REUSE the token for an unchanged asset (in-flight streams
+  // survive), prune assets that vanished, and only an explicit ?refresh=1
+  // re-mints everything.
   const tokens = new Map();
+  const tokenByKey = new Map();
   const mint = (entry) => {
+    const key = entry && entry.key;
+    if (key && tokenByKey.has(key)) return tokenByKey.get(key);
     const token = randomBytes(9).toString('base64url'); // 72 bits, url-safe
     tokens.set(token, entry);
+    if (key) tokenByKey.set(key, token);
     return token;
   };
+  const remintAll = () => { tokens.clear(); tokenByKey.clear(); };
+  const pruneTokens = (payload) => {
+    const live = new Set();
+    for (const w of payload.wallpapers) {
+      for (const url of [w.media, w.preview]) {
+        if (!url) continue;
+        const token = url.slice(url.lastIndexOf('/') + 1);
+        live.add(token);
+      }
+    }
+    for (const token of [...tokens.keys()]) {
+      if (!live.has(token)) {
+        const entry = tokens.get(token);
+        tokens.delete(token);
+        if (entry && entry.key && tokenByKey.get(entry.key) === token) {
+          tokenByKey.delete(entry.key);
+        }
+      }
+    }
+  };
 
   // ── Inventory (cached) ──────────────────────────────────────────────────
   let cache = null; // { at: number, payload: object }
+  let discoveryCache = null; // { at: number, value: object }
+  let building = null; // in-flight build promise (request coalescing)
 
-  // Discovery is expensive (reg.exe + vdf scan) and the install layout barely
-  // changes — resolve it ONCE and reuse across builds; only an explicit
-  // refresh (or TTL expiry on the first build) forces a re-discovery.
-  let discoveryCache = null;
-  function getDiscovery(force) {
-    if (!force && discoveryCache) return discoveryCache;
-    discoveryCache = discover();
-    return discoveryCache;
+  async function getDiscovery(force) {
+    const fresh = discoveryCache && Date.now() - discoveryCache.at < discoveryTtlMs;
+    if (!force && fresh) return discoveryCache.value;
+    const value = await discoverFn();
+    discoveryCache = { at: Date.now(), value };
+    return value;
   }
 
-  function buildInventory(force) {
-    tokens.clear(); // re-mint: tokens from older builds stop resolving
-    return core.buildInventoryFrom(getDiscovery(force), { mint });
+  async function buildInventory(force) {
+    if (force) remintAll(); // explicit refresh: stale URLs die on purpose
+    const payload = await core.buildInventoryFrom(await getDiscovery(force), {
+      ...asyncIo,
+      mint,
+      base: BASE,
+    });
+    pruneTokens(payload);
+    return payload;
   }
 
   function getInventory(force) {
-    if (!force && cache && Date.now() - cache.at < INVENTORY_TTL_MS) return cache.payload;
-    const payload = buildInventory(force);
-    cache = { at: Date.now(), payload };
-    return payload;
+    if (!force && cache && Date.now() - cache.at < inventoryTtlMs) {
+      return Promise.resolve(cache.payload);
+    }
+    // Coalesce concurrent builds (double-clicked 刷新, parallel clients).
+    if (building) return building;
+    building = buildInventory(force)
+      .then((payload) => { cache = { at: Date.now(), payload }; return payload; })
+      .finally(() => { building = null; });
+    return building;
   }
 
   // ── Response helpers ────────────────────────────────────────────────────
-  function sendJson(res, status, body) {
+  function sendJson(req, res, status, body) {
+    const text = JSON.stringify(body);
     res.statusCode = status;
     res.setHeader('Content-Type', 'application/json; charset=utf-8');
     res.setHeader('Cache-Control', 'no-store');
-    res.end(JSON.stringify(body));
+    res.setHeader('Content-Length', String(Buffer.byteLength(text)));
+    res.end(req.method === 'HEAD' ? undefined : text);
   }
 
   /** Stream one file with Range support (video seeking) and HEAD handling. */
   function serveFile(absPath, req, res) {
-    let st;
-    try { st = statSync(absPath); } catch { st = null; }
-    if (!st || !st.isFile()) {
-      res.statusCode = 404;
-      res.end('not found');
-      return;
-    }
-    res.setHeader('Content-Type', core.mimeFor(absPath));
-    res.setHeader('Accept-Ranges', 'bytes');
-    res.setHeader('Cache-Control', 'no-store');
-    res.setHeader('X-Content-Type-Options', 'nosniff');
+    fsp.stat(absPath).then((st) => {
+      if (!st.isFile()) {
+        res.statusCode = 404;
+        res.setHeader('Content-Length', '0');
+        res.end();
+        return;
+      }
+      res.setHeader('Content-Type', core.mimeFor(absPath));
+      res.setHeader('Accept-Ranges', 'bytes');
+      res.setHeader('Cache-Control', 'no-store');
+      res.setHeader('X-Content-Type-Options', 'nosniff');
 
-    const range = core.parseRangeHeader(req.headers.range, st.size);
-    if (range && range.error) {
-      res.statusCode = 416;
-      res.setHeader('Content-Range', `bytes */${st.size}`);
-      res.end();
-      return;
-    }
-    const head = req.method === 'HEAD';
-    if (range) {
-      res.statusCode = 206;
-      res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${st.size}`);
-      res.setHeader('Content-Length', String(range.end - range.start + 1));
-    } else {
-      res.setHeader('Content-Length', String(st.size));
-    }
-    if (head) { res.end(); return; }
+      const range = core.parseRangeHeader(req.headers.range, st.size);
+      if (range && range.error) {
+        res.statusCode = 416;
+        res.setHeader('Content-Range', `bytes */${st.size}`);
+        res.setHeader('Content-Length', '0');
+        res.end();
+        return;
+      }
+      const head = req.method === 'HEAD';
+      if (range) {
+        res.statusCode = 206;
+        res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${st.size}`);
+        res.setHeader('Content-Length', String(range.end - range.start + 1));
+      } else {
+        res.setHeader('Content-Length', String(st.size));
+      }
+      if (head) { res.end(); return; }
 
-    const stream = range
-      ? createReadStream(absPath, { start: range.start, end: range.end })
-      : createReadStream(absPath);
-    stream.on('error', () => {
-      if (!res.headersSent) res.statusCode = 500;
+      const stream = range
+        ? createReadStream(absPath, { start: range.start, end: range.end })
+        : createReadStream(absPath);
+      // The file can vanish between stat and open; ending normally would
+      // leave the already-announced Content-Length unsatisfied and the
+      // client hanging — destroy the response instead.
+      stream.on('error', () => { res.destroy(); });
+      stream.pipe(res);
+    }).catch(() => {
+      res.statusCode = 404;
+      res.setHeader('Content-Length', '0');
       res.end();
     });
-    stream.pipe(res);
   }
 
   // ── Routes ──────────────────────────────────────────────────────────────
@@ -184,20 +253,15 @@ export function apply(ctx) {
     path: `${BASE}/inventory`,
     handler: (req, res) => {
       if (req.method !== 'GET' && req.method !== 'HEAD') {
-        sendJson(res, 405, { error: 'method not allowed' });
+        sendJson(req, res, 405, { error: 'method not allowed' });
         return;
       }
-      try {
-        const url = new URL(req.url || '/', 'http://x');
-        const payload = JSON.stringify(getInventory(url.searchParams.get('refresh') === '1'));
-        res.statusCode = 200;
-        res.setHeader('Content-Type', 'application/json; charset=utf-8');
-        res.setHeader('Cache-Control', 'no-store');
-        res.setHeader('Content-Length', String(Buffer.byteLength(payload)));
-        res.end(req.method === 'HEAD' ? undefined : payload);
-      } catch (err) {
-        sendJson(res, 500, { error: String(err && err.message ? err.message : err) });
-      }
+      const url = new URL(req.url || '/', 'http://x');
+      getInventory(url.searchParams.get('refresh') === '1')
+        .then((payload) => sendJson(req, res, 200, payload))
+        .catch((err) => {
+          sendJson(req, res, 500, { error: String(err && err.message ? err.message : err) });
+        });
     },
   }));
 
@@ -208,14 +272,14 @@ export function apply(ctx) {
       path: `${BASE}/${seg}`,
       handler: (req, res) => {
         if (req.method !== 'GET' && req.method !== 'HEAD') {
-          sendJson(res, 405, { error: 'method not allowed' });
+          sendJson(req, res, 405, { error: 'method not allowed' });
           return;
         }
         let pathname;
         try {
           pathname = new URL(req.url || '/', 'http://x').pathname;
         } catch {
-          sendJson(res, 400, { error: 'bad request' });
+          sendJson(req, res, 400, { error: 'bad request' });
           return;
         }
         const rest = pathname.slice(prefix.length); // "<token>" | "<token>/<rel…>"
@@ -223,14 +287,14 @@ export function apply(ctx) {
         const rawToken = slash < 0 ? rest : rest.slice(0, slash);
         let token;
         try { token = decodeURIComponent(rawToken); } catch {
-          sendJson(res, 400, { error: 'bad token' });
+          sendJson(req, res, 400, { error: 'bad token' });
           return;
         }
         const entry = tokens.get(token);
         if (!entry) {
           res.statusCode = 404;
-          if (req.method === 'HEAD') res.end();
-          else res.end('not found');
+          res.setHeader('Content-Length', '0');
+          res.end();
           return;
         }
         let abs = entry.abs;
@@ -238,22 +302,25 @@ export function apply(ctx) {
           // Sub-asset of a bundled web wallpaper: must stay inside its dir.
           if (seg !== 'media' || !entry.rootDir) {
             res.statusCode = 404;
-            if (req.method === 'HEAD') res.end();
-            else res.end('not found');
+            res.setHeader('Content-Length', '0');
+            res.end();
             return;
           }
           let rel;
           try { rel = decodeURIComponent(rest.slice(slash + 1)); } catch {
-            sendJson(res, 400, { error: 'bad path' });
+            sendJson(req, res, 400, { error: 'bad path' });
             return;
           }
-          if (!rel || rel.split('/').some((part) => part === '..' || part === '')) {
-            sendJson(res, 403, { error: 'forbidden' });
+          // Backslash parts are never legitimate in a URL path here; on win32
+          // `..\evil` would slip past a `/`-only split (the isInsideDir
+          // backstop still catches it — this is defense in depth).
+          if (!rel || rel.split('/').some((part) => part === '..' || part === '' || part.includes('\\'))) {
+            sendJson(req, res, 403, { error: 'forbidden' });
             return;
           }
           abs = join(entry.rootDir, ...rel.split('/'));
           if (!core.isInsideDir(entry.rootDir, abs)) {
-            sendJson(res, 403, { error: 'forbidden' });
+            sendJson(req, res, 403, { error: 'forbidden' });
             return;
           }
         }
@@ -262,17 +329,24 @@ export function apply(ctx) {
     }));
   }
 
-  // Warm the discovery cache now (reg.exe + vdf scan) so the first inventory
-  // request answers immediately instead of paying the discovery cost inline.
-  try { getDiscovery(false); } catch { /* non-fatal: inventory will 500 with reason */ }
+  // Warm the discovery cache now (async, off the request path) so the first
+  // inventory request answers quickly.
+  getDiscovery(false).catch(() => { /* non-fatal: inventory will 500 with reason */ });
 
   return () => {
     for (const d of disposers) { try { d(); } catch { /* ignore */ } }
     disposers.length = 0;
-    tokens.clear();
+    remintAll();
     cache = null;
     discoveryCache = null;
   };
 }
 
+export const inject = ['webServer'];
+
+export function apply(ctx) {
+  // inject guarantees the service is present before apply runs.
+  return createRouteRegistrar(ctx.webServer);
+}
+
 export default { inject, apply };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wallpaper-engine-dsh",
-  "version": "0.1.4",
-  "description": "Wallpaper Engine Video/Web wallpapers as the DSH web GUI background — discovery, sandboxed rendering, rotation lists, liquid-glass tuning.",
+  "version": "0.1.6",
+  "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",
   "types": "lib/types/index.d.ts",
@@ -9,10 +9,14 @@
     "type": "git",
     "url": "git+https://github.com/Weilv-D/wallpaper-engine-dsh.git"
   },
+  "bugs": "https://github.com/Weilv-D/wallpaper-engine-dsh/issues",
+  "homepage": "https://github.com/Weilv-D/wallpaper-engine-dsh#readme",
   "keywords": [
     "dsh",
     "dsh-plugin",
+    "deepseek",
     "deepseek-harness",
+    "cordis",
     "wallpaper",
     "wallpaper-engine",
     "background",
@@ -59,7 +63,7 @@
   "scripts": {
     "build": "node scripts/build-client.mjs",
     "verify": "node scripts/verify-client.mjs",
-    "test": "node --test test/core.test.mjs",
+    "test": "node --test test/core.test.mjs test/host.test.mjs",
     "prepare": "node scripts/prepare.mjs",
     "prepublishOnly": "npm run test && npm run build && npm run verify",
     "release": "npm version patch -m \"chore: release v%s\" && git push --follow-tags",