wallpaper-engine-dsh 0.1.7 → 0.1.9

package/README.md

@@ -2,16 +2,16 @@
 
 [English](README.md) | [中文](README.zh.md)
 
-A DSH bundle that turns your local **Wallpaper Engine** library into the live background of the DSH web GUI (`dsh web`). Video wallpapers play behind the chat, web wallpapers render in place, and scene/application wallpapers join in as still images — with crossfade transitions, liquid-glass panels, rotation lists, search, a resource monitor, and a bilingual UI.
+A DSH bundle that turns your local **Wallpaper Engine** library into the live background of the DSH web GUI (`dsh web`). Video wallpapers play behind the chat and web wallpapers render in place — with crossfade transitions, liquid-glass panels, rotation lists, search, a resource monitor, and a bilingual UI.
 
 ## Features
 
-- **Whole-library browsing** — video and web wallpapers render live; scene and application wallpapers show their preview as a static background. Everything with a preview or playable file is selectable, badged by type (Video / Web / Still).
+- **Renderable-only browsing** — video and web wallpapers render live and are the only kinds listed: scene and application wallpapers are Wallpaper Engine's private `.pkg` scene packages, which no browser can render, so they are filtered out instead of offered as degraded stills. A video the browser cannot decode falls back to its preview image until you refresh.
 - **Search** — filter the grid instantly by title or workshop id.
 - **Rotation lists** — any number of carousel lists, each with its own wallpapers, interval (1–120 min) and order (sequence/random). Your first playable Wallpaper Engine playlist is imported automatically; others can be imported into any list.
 - **Four live sliders** — Wallpaper blur, Scrim, Borders, Glass — all instant and persisted.
 - **Legibility on any wallpaper** — the veil opposes the text colour (white veil in light theme, black in dark) and a Smart veil toggle samples the wallpaper's brightness every few seconds, automatically strengthening the veil when a scene gets too bright or too dark for the current theme. Dropdowns, menus, and dialogs keep DSH's opaque surfaces untouched.
-- **Canvas fit** — Cover/Contain/Stretch/Original sizing plus five-way alignment for video and still wallpapers.
+- **Manual crop** — pick a base layout (Cover/Contain/Stretch/Original), then frame it yourself: **Adjust** opens the live wallpaper fullscreen where you drag to pan and scroll to zoom; **Reset crop** restores it.
 - **Resource monitor** — FPS readout with a low-framerate hint, plus auto-pause when the tab is hidden or the battery runs low (both optional).
 - **Bilingual** — the settings UI follows the shell's Language preference (Chinese/English), with a manual override in the picker.
 - **Crossfade** — wallpaper switches and clearing fade smoothly instead of snapping.
@@ -35,7 +35,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. The **Fit/Align** row sets how video and still wallpapers sit on the canvas (cover/contain/stretch/original, five anchor points).
+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** row sets the base layout for video and still wallpapers — **Adjust** then lets you pan and zoom the crop directly on the canvas.
 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.
@@ -50,13 +50,13 @@ 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. 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.
+- 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 that repeatedly fails to decode (an unsupported container) falls back to its preview still, and the next Refresh retries the live media.
 
 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
 
-- Scene and application wallpapers render as still images; their live animation remains Wallpaper Engine's desktop job.
+- Scene and application wallpapers are not listed at all: they are Wallpaper Engine's private `.pkg` scene packages, and their live animation can only be rendered by Wallpaper Engine itself on the desktop.
 - Web wallpapers run isolated from the page's storage, so ones that persist state across loads won't keep it.
 - The glass effect reads DSH design tokens; if a future shell redesign renames them, frosting degrades to plain transparency.
 

package/README.zh.md

@@ -2,16 +2,16 @@
 
 [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 即时筛选网格。
 - **轮播列表** —— 可建任意多个列表，各自拥有壁纸集合、切换间隔（1–120 分钟）和顺序（顺序/随机）。首次运行自动导入第一个可播放的 Wallpaper Engine 播放列表，其余列表可随时导入。
 - **四个实时滑杆** —— 壁纸模糊、暗化、边框、玻璃，即时生效并持久保存。
 - **任意壁纸都可读** —— 遮罩颜色与文字颜色相对（浅色主题提亮、深色主题压暗）;"智能可视"开关每隔几秒采样一次壁纸亮度，画面过亮或过暗时自动加强遮罩。下拉菜单、弹窗等浮层保持 DSH 原生不透明表面，不受影响。
-- **画布排布** —— 视频与静态壁纸支持填充/适应/拉伸/原始四种排布和五向对齐。
+- **手动裁剪** —— 先选基础排布（填充/适应/拉伸/原始），再自己取景：点「调整画面」把壁纸全屏展开，拖动平移、滚轮缩放，「重置裁剪」一键还原。
 - **资源监控** —— 帧率读数与低帧率提示，页面隐藏或电量不足时自动暂停（均可开关）。
 - **中英双语** —— 设置界面跟随 DSH 的"语言"偏好自动切换，也可在面板内手动指定。
 - **交叉淡入** —— 切换与关闭都平滑过渡，不生硬跳变。
@@ -35,7 +35,7 @@ dsh plugin --profile web add link:<克隆文件夹的绝对路径>
 
 1. 从缩略图网格选择壁纸，它会在界面背后淡入。壁纸库较大时用搜索框快速定位。
 2. **暂停/播放** 控制视频播放；**关闭** 淡出壁纸；**刷新** 重新扫描壁纸库，新订阅的创意工坊壁纸无需刷新页面即可出现。
-3. 用滑杆调节融合效果。壁纸太花时调高 **暗化** 和 **边框** 直到文字清晰；界面跟随 DSH 明暗主题自动适配。**排布/对齐** 一行设置视频与静态壁纸在画布上的摆放（填充/适应/拉伸/原始，五个锚点）。
+3. 用滑杆调节融合效果。壁纸太花时调高 **暗化** 和 **边框** 直到文字清晰；界面跟随 DSH 明暗主题自动适配。**排布** 一行决定视频与静态壁纸的基础摆放（填充/适应/拉伸/原始），点「调整画面」可在画布上直接拖动平移、滚轮缩放取景。
 4. 用 **新建** 创建轮播列表，从网格挑选或导入 WE 播放列表，然后开启 **自动轮转**。
 5. 资源行显示当前帧率，并提供两个自动暂停开关。系统开启 `prefers-reduced-motion` 时视频默认暂停。
 6. "语言"控件在中英文之间切换面板；选"自动"则跟随 DSH 的语言设置。
@@ -50,13 +50,13 @@ bundle 分为两半：
   - `GET /we-background/inventory[?refresh=1]`
   - `GET /we-background/media/<token>[/资源…]` —— 支持 HTTP Range，视频可拖动进度；网页壁纸可加载其打包的子资源
   - `GET /we-background/preview/<token>`
-- **浏览器插件** 把选中的壁纸渲染在应用框架之下的固定层，提供设置界面，所有视觉效果都读 DSH 设计令牌，主题切换自然生效。壁纸模糊采用裁边式超采样（内容不变形），叠加微量抖动噪声消除渐变色带；浏览器解不了的视频会自动改用该壁纸的预览图。
+- **浏览器插件** 把选中的壁纸渲染在应用框架之下的固定层，提供设置界面，所有视觉效果都读 DSH 设计令牌，主题切换自然生效。壁纸模糊采用裁边式超采样（内容不变形），叠加微量抖动噪声消除渐变色带；反复解码失败的视频（不支持的容器）退到预览图，下次刷新重试原媒体。
 
 清单由宿主缓存 30 秒，媒体令牌按壁纸稳定复用（后台重建不会掐断播放中的流）；安装发现异步执行并缓存 10 分钟。本插件不注册模型工具，不占用 prompt。
 
 ## 限制
 
-- 场景与应用壁纸以静态图呈现，其动态渲染仍是 Wallpaper Engine 桌面的职责。
+- 场景与应用壁纸完全不出现在列表里：它们是 Wallpaper Engine 私有的 `.pkg` 场景包，动态渲染只能由桌面端的 Wallpaper Engine 完成。
 - 网页壁纸与页面存储隔离，需要跨加载保存状态的壁纸无法保留状态。
 - 玻璃效果读 DSH 设计令牌；若未来外壳重构重命名令牌，磨砂会退化为普通半透明。
 

package/lib/client.js

@@ -48,7 +48,6 @@ window.__ModuleLoader__.load({
 		    noPreview: "无预览",
 		    badgeVideo: "视频",
 		    badgeWeb: "网页",
-		    badgeStill: "静态",
 		    rotationList: "轮播列表",
 		    selectList: "— 选择轮播列表 —",
 		    noLists: "— 暂无轮播列表 —",
@@ -90,12 +89,10 @@ window.__ModuleLoader__.load({
 		    fitContain: "适应",
 		    fitFill: "拉伸",
 		    fitNone: "原始",
-		    position: "对齐",
-		    posCenter: "居中",
-		    posTop: "顶部",
-		    posBottom: "底部",
-		    posLeft: "居左",
-		    posRight: "居右",
+		    adjust: "调整画面",
+		    adjustDone: "完成",
+		    adjustHint: "拖动平移 · 滚轮缩放 · Esc 或点「完成」退出",
+		    resetCrop: "重置裁剪",
 		    statusGroup: (name, total, usable, interval, order) =>
 		      "列表「" + name + "」:" + total + " 项 · " + usable + " 可用 · 每 " + interval + " 分钟 · " + order,
 		    statusUsable: (n) => n + " 张可用壁纸",
@@ -128,7 +125,6 @@ window.__ModuleLoader__.load({
 		    noPreview: "No preview",
 		    badgeVideo: "Video",
 		    badgeWeb: "Web",
-		    badgeStill: "Still",
 		    rotationList: "Rotation list",
 		    selectList: "— Select a list —",
 		    noLists: "— No lists yet —",
@@ -170,12 +166,10 @@ window.__ModuleLoader__.load({
 		    fitContain: "Contain",
 		    fitFill: "Stretch",
 		    fitNone: "Original",
-		    position: "Align",
-		    posCenter: "Center",
-		    posTop: "Top",
-		    posBottom: "Bottom",
-		    posLeft: "Left",
-		    posRight: "Right",
+		    adjust: "Adjust",
+		    adjustDone: "Done",
+		    adjustHint: "Drag to pan · wheel to zoom · Esc or Done to exit",
+		    resetCrop: "Reset crop",
 		    statusGroup: (name, total, usable, interval, order) =>
 		      "List \"" + name + "\": " + total + " items · " + usable + " usable · every " + interval + " min · " + order,
 		    statusUsable: (n) => n + " usable wallpapers",
@@ -225,11 +219,12 @@ window.__ModuleLoader__.load({
 		  autoScrim: true,
 		  lang: "auto",
 		  fit: "cover",
-		  position: "center",
+		  zoom: 1,
+		  offsetX: 0,
+		  offsetY: 0,
 		};
 
 		const FIT_MODES = ["cover", "contain", "fill", "none"];
-		const POSITIONS = ["center", "top", "bottom", "left", "right"];
 
 		// ── Persisted selection ─────────────────────────────────────────────────────
 		function clampNum(v, lo, hi, fallback) {
@@ -276,7 +271,9 @@ 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,
-		      position: POSITIONS.indexOf(o.position) >= 0 ? o.position : DEFAULTS.position,
+		      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),
 		    };
 		  } catch {
 		    return { id: "", ...DEFAULTS };
@@ -288,6 +285,7 @@ window.__ModuleLoader__.load({
 		  ...readPersisted(),
 		  url: null,
 		  type: null,
+		  adjusting: false, // crop-adjust overlay open (not persisted)
 		  playing: !REDUCED_MOTION,
 		  loading: false,
 		  rotationTimer: null,
@@ -328,24 +326,25 @@ window.__ModuleLoader__.load({
 		      autoScrim: selection.autoScrim,
 		      lang: selection.lang,
 		      fit: selection.fit,
-		      position: selection.position,
+		      zoom: selection.zoom,
+		      offsetX: selection.offsetX,
+		      offsetY: selection.offsetY,
 		    }));
 		  } catch { /* storage full / blocked → session-only state, not fatal */ }
 		}
 
 		// ── Wallpaper predicates ─────────────────────────────────────────────────────
 		// playable: real media (video/web) renders live.
-		// static:   scene/application with a preview image renders as a still.
+		// Renderable kinds ONLY — scene/application wallpapers are .pkg scene
+		// packages the browser cannot render (their live animation is Wallpaper
+		// Engine's desktop job), so they are filtered out of the grid entirely
+		// rather than offered as degraded preview stills.
 		function isPlayable(w) {
 		  return Boolean(w && w.playable && (w.type === "video" || w.type === "web"));
 		}
 
-		function isStatic(w) {
-		  return Boolean(w && !isPlayable(w) && typeof w.preview === "string" && w.preview);
-		}
-
 		function isSelectable(w) {
-		  return isPlayable(w) || isStatic(w);
+		  return isPlayable(w);
 		}
 
 		function selectableInventory() {
@@ -353,13 +352,22 @@ window.__ModuleLoader__.load({
 		}
 
 		// ── Inventory ────────────────────────────────────────────────────────────────
+		// Monotonic token for in-flight inventory fetches: a fetch that started
+		// before a newer one must not commit its (older) state afterwards, and a
+		// fetch still in flight at dispose must not commit anything at all — its
+		// applySelection call would re-arm the rotation timer on a torn-down store.
+		let inventoryEpoch = 0;
+		let disposed = false;
+
 		async function loadInventory(forceRefresh) {
+		  const epoch = ++inventoryEpoch;
 		  selection.loading = true;
 		  emit();
 		  try {
 		    const res = await fetch(forceRefresh ? INVENTORY_URL + "?refresh=1" : INVENTORY_URL, { cache: "no-store" });
 		    if (!res.ok) throw new Error("inventory HTTP " + res.status);
 		    const data = await res.json();
+		    if (disposed || epoch !== inventoryEpoch) return;
 		    selection.inventory = {
 		      installDir: data.installDir || null,
 		      wallpapers: Array.isArray(data.wallpapers) ? data.wallpapers : [],
@@ -369,11 +377,13 @@ window.__ModuleLoader__.load({
 		      error: null,
 		    };
 		  } catch (err) {
+		    if (disposed || epoch !== inventoryEpoch) return;
 		    selection.inventory = {
 		      installDir: null, wallpapers: [], total: 0, portableCount: 0, playlists: [],
 		      error: String(err && err.message ? err.message : err),
 		    };
 		  }
+		  if (disposed || epoch !== inventoryEpoch) return;
 		  selection.loading = false;
 		  selection.loaded = true;
 
@@ -582,6 +592,7 @@ window.__ModuleLoader__.load({
 		}
 
 		function applySelection(id) {
+		  if (selection.adjusting) exitAdjust();
 		  selection.id = id || "";
 		  persistSelection();
 		  const w = selection.id
@@ -590,9 +601,9 @@ window.__ModuleLoader__.load({
 		  if (isPlayable(w) && !demotedToPreview.has(selection.id)) {
 		    selection.url = w.media;
 		    selection.type = w.type; // "video" | "web"
-		  } else if (w && w.preview) {
-		    // Static path: scene/application wallpapers, and playable wallpapers
-		    // demoted after repeated media failures (undecodable container…).
+		  } else if (isPlayable(w) && w.preview) {
+		    // Playable wallpaper demoted after repeated media failures (an
+		    // undecodable container) — its preview still is the graceful fallback.
 		    selection.url = w.preview;
 		    selection.type = "image";
 		  } else {
@@ -629,11 +640,10 @@ window.__ModuleLoader__.load({
 		// 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.
+		// Per-wallpaper recovery timestamps: the first error for a wallpaper may
+		// just be a stale token; a SECOND error for the same id means the bytes are
+		// unusable — demote it to its preview instead of looping forever.
+		const lastRecoveryAt = new Map(); // wallpaperId → last recovery timestamp
 		const mediaFailures = new Map(); // wallpaperId → consecutive failure count
 		const demotedToPreview = new Set(); // wallpaperIds now rendered as stills
 
@@ -659,7 +669,8 @@ window.__ModuleLoader__.load({
 		    media.setAttribute("title", S().iframeTitle);
 		    media.className = "webg-media webg-iframe";
 		  } else {
-		    // Static wallpaper: the scene/application preview as a still image.
+		    // Static fallback: a playable wallpaper demoted after repeated media
+		    // failures — its preview still beats a black screen.
 		    media = document.createElement("img");
 		    media.src = sel.url;
 		    media.alt = "";
@@ -667,33 +678,169 @@ window.__ModuleLoader__.load({
 		    media.setAttribute("decoding", "async");
 		    media.className = "webg-media";
 		  }
-		  // First luminance sample as soon as the frame is decodable (video/still
-		  // only — iframe contents are opaque to us). Later samples ride the timer.
-		  if (sel.type === "video" || sel.type === "image") {
-		    media.addEventListener(sel.type === "video" ? "loadeddata" : "load", () => {
-		      sampleWallpaperLuminance();
-		      applyEffects();
-		    });
-		  }
+		  attachStillSampling(media, sel);
+		  attachMediaError(media, sel);
+		  return media;
+		}
+
+		function attachStillSampling(media, sel) {
+		  const type = (sel && sel.type) || (media.tagName === "IMG" ? "image" : null);
+		  if (type !== "video" && type !== "image") return;
+		  media.addEventListener(type === "video" ? "loadeddata" : "load", () => {
+		    sampleWallpaperLuminance();
+		    applyEffects();
+		  });
+		}
+
+		function attachMediaError(media, sel) {
 		  media.addEventListener("error", () => {
 		    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).
+		      // Maybe just a dead token: refetch fresh URLs and remount. Throttled
+		      // PER WALLPAPER — a global window would strand a video whose first
+		      // error lands soon after an unrelated recovery (no remount, no second
+		      // error, blank layer until a manual refresh).
 		      const now = Date.now();
-		      if (now - lastMediaRecoveryAt < 10000) return;
-		      lastMediaRecoveryAt = now;
+		      if (now - (lastRecoveryAt.get(id) || 0) < 10000) return;
+		      lastRecoveryAt.set(id, 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);
+		    } 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.
+		      applySelection("");
 		    }
 		  });
-		  return media;
+		}
+
+		// ── Manual crop: drag-to-pan / wheel-to-zoom in an adjust overlay ───────────
+		// The layer normally sits at z-index -2 behind the entire app, so it can
+		// never receive pointer events. Adjust mode moves the LIVE layer node into a
+		// topmost transparent overlay — the user edits the real thing, WYSIWYG.
+		let adjustOverlay = null;
+		let adjustCleanup = null;
+
+		function exitAdjust() {
+		  if (!adjustOverlay) return;
+		  const layer = document.getElementById(LAYER_ID);
+		  if (adjustCleanup) adjustCleanup();
+		  if (layer) document.body.appendChild(layer); // move back behind the app
+		  adjustOverlay.remove();
+		  adjustOverlay = null;
+		  adjustCleanup = null;
+		  selection.adjusting = false;
+		  persistSelection();
+		  emit();
+		}
+
+		function enterAdjust() {
+		  const layer = document.getElementById(LAYER_ID);
+		  if (!layer || adjustOverlay) return;
+		  const overlay = document.createElement("div");
+		  overlay.className = "webg-adjust";
+		  overlay.appendChild(layer); // moves the live node into the overlay
+
+		  const bar = document.createElement("div");
+		  bar.className = "webg-adjust-bar";
+		  const hint = document.createElement("span");
+		  hint.className = "webg-adjust-hint";
+		  hint.textContent = S().adjustHint;
+		  const done = document.createElement("button");
+		  done.type = "button";
+		  done.className = "webg-btn webg-btn--primary";
+		  done.textContent = S().adjustDone;
+		  bar.appendChild(hint);
+		  bar.appendChild(done);
+		  overlay.appendChild(bar);
+		  document.body.appendChild(overlay);
+		  adjustOverlay = overlay;
+		  selection.adjusting = true;
+
+		  // translate() in the transform list is applied AFTER scale() (right-to-
+		  // left), so pan deltas are independent of zoom: dx px = dx/width %.
+		  let drag = null;
+		  const onPointerDown = (e) => {
+		    if (e.target === done || bar.contains(e.target)) return;
+		    drag = { x: e.clientX, y: e.clientY };
+		    if (overlay.setPointerCapture && e.pointerId !== undefined) {
+		      try { overlay.setPointerCapture(e.pointerId); } catch {}
+		    }
+		  };
+		  const onPointerMove = (e) => {
+		    if (!drag) return;
+		    // translate % refers to the MEDIA BOX, which (blur overscan) is wider
+		    // than the viewport by 2× the wallpaper blur — divide by that, so the
+		    // content tracks the cursor 1:1 at any blur setting.
+		    const w = (overlay.clientWidth || 1) + 2 * selection.wallpaperBlur;
+		    const h = (overlay.clientHeight || 1) + 2 * selection.wallpaperBlur;
+		    // True clamping (clampNum is a validate-or-fallback for persisted data).
+		    selection.offsetX = Math.min(200, Math.max(-200,
+		      selection.offsetX + ((e.clientX - drag.x) / w) * 100));
+		    selection.offsetY = Math.min(200, Math.max(-200,
+		      selection.offsetY + ((e.clientY - drag.y) / h) * 100));
+		    drag = { x: e.clientX, y: e.clientY };
+		    applyEffects();
+		  };
+		  const onPointerUp = () => {
+		    if (!drag) return;
+		    drag = null;
+		    persistSelection();
+		  };
+		  // pointercancel (touch gesture takeover): end the drag without losing the
+		  // current offsets — otherwise drag stays "stuck" until the next pointerup.
+		  const onPointerCancel = () => {
+		    if (!drag) return;
+		    drag = null;
+		    persistSelection();
+		  };
+		  const onWheel = (e) => {
+		    if (typeof e.preventDefault === "function") e.preventDefault();
+		    // True clamping to [0.25, 4] — clampNum is a validate-or-fallback for
+		    // persisted data and would REJECT an out-of-range zoom instead of
+		    // pinning it to the boundary.
+		    const next = Math.min(4, Math.max(0.25,
+		      selection.zoom * Math.exp(-(e.deltaY || 0) * 0.0012)));
+		    selection.zoom = Math.round(next * 100) / 100;
+		    applyEffects();
+		    persistSelection();
+		  };
+		  const onKey = (e) => { if (e.key === "Escape") exitAdjust(); };
+		  const onDone = () => exitAdjust();
+
+		  overlay.addEventListener("pointerdown", onPointerDown);
+		  overlay.addEventListener("pointermove", onPointerMove);
+		  overlay.addEventListener("pointerup", onPointerUp);
+		  overlay.addEventListener("pointercancel", onPointerCancel);
+		  overlay.addEventListener("wheel", onWheel, { passive: false });
+		  done.addEventListener("click", onDone);
+		  document.addEventListener("keydown", onKey);
+
+		  adjustCleanup = () => {
+		    overlay.removeEventListener("pointerdown", onPointerDown);
+		    overlay.removeEventListener("pointermove", onPointerMove);
+		    overlay.removeEventListener("pointerup", onPointerUp);
+		    overlay.removeEventListener("pointercancel", onPointerCancel);
+		    overlay.removeEventListener("wheel", onWheel);
+		    done.removeEventListener("click", onDone);
+		    document.removeEventListener("keydown", onKey);
+		  };
+		  emit();
+		}
+
+		function resetCrop() {
+		  selection.zoom = 1;
+		  selection.offsetX = 0;
+		  selection.offsetY = 0;
+		  persistSelection();
+		  applyEffects();
+		  emit();
 		}
 
 		// Crossfade/clear leave timers: tracked so dispose can cancel them instead of
@@ -801,6 +948,7 @@ window.__ModuleLoader__.load({
 		    const g = sampleCanvas.getContext("2d", { willReadFrequently: true });
 		    g.drawImage(media, 0, 0, 16, 16);
 		    const d = g.getImageData(0, 0, 16, 16).data;
+		    if (!d || d.length < 4) return; // unreadable frame → keep previous sample
 		    let sum = 0;
 		    for (let i = 0; i < d.length; i += 4) {
 		      sum += 0.299 * d[i] + 0.587 * d[i + 1] + 0.114 * d[i + 2];
@@ -832,13 +980,25 @@ 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");
+		  // At 0 blur, keep the media OUT of the filter pipeline entirely: even
+		  // blur(0px) forces an extra raster/compositing pass, and the noise overlay
+		  // would still occupy a layer at opacity 0. filter:none + display:none keep
+		  // the pixels bit-exact and the layer list minimal.
+		  s.setProperty("--webg-media-filter",
+		    selection.wallpaperBlur > 0
+		      ? "blur(" + selection.wallpaperBlur + "px) saturate(1.08)"
+		      : "none");
+		  s.setProperty("--webg-noise-display", selection.wallpaperBlur > 0 ? "block" : "none");
 		  // 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).
+		  // 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);
-		  s.setProperty("--webg-position", selection.position);
+		  s.setProperty("--webg-zoom", String(selection.zoom));
+		  s.setProperty("--webg-offset-x", selection.offsetX + "%");
+		  s.setProperty("--webg-offset-y", selection.offsetY + "%");
 
 		  // Write the scrim colour directly too, then force a synchronous layout, so
 		  // slider feedback lands on this frame even on stalled compositors.
@@ -857,9 +1017,13 @@ window.__ModuleLoader__.load({
 		  s.removeProperty("--webg-saturate");
 		  s.removeProperty("--webg-glass-brightness");
 		  s.removeProperty("--webg-wallpaper-blur");
+		  s.removeProperty("--webg-media-filter");
+		  s.removeProperty("--webg-noise-display");
 		  s.removeProperty("--webg-noise-opacity");
 		  s.removeProperty("--webg-fit");
-		  s.removeProperty("--webg-position");
+		  s.removeProperty("--webg-zoom");
+		  s.removeProperty("--webg-offset-x");
+		  s.removeProperty("--webg-offset-y");
 		  const scrim = document.getElementById(SCRIM_ID);
 		  if (scrim) scrim.style.background = "";
 		}
@@ -886,7 +1050,9 @@ window.__ModuleLoader__.load({
 		      min: String(min), max: String(max), step: String(step),
 		      value: String(value),
 		      style: { "--webg-p": String(pct) },
-		      onInput: set,
+		      // React normalizes onChange on range inputs to the DOM input event —
+		      // it fires CONTINUOUSLY while dragging. Registering onInput too would
+		      // run the handler twice per tick.
 		      onChange: set,
 		    }),
 		    React.createElement("span", { className: "webg-hint webg-value" }, suffix),
@@ -895,8 +1061,7 @@ window.__ModuleLoader__.load({
 
 		function typeBadge(w, t) {
 		  if (w.type === "video") return t.badgeVideo;
-		  if (w.type === "web") return t.badgeWeb;
-		  return t.badgeStill;
+		  return t.badgeWeb;
 		}
 
 		function matchesQuery(w, q) {
@@ -936,6 +1101,7 @@ window.__ModuleLoader__.load({
 		    // preview after decode failures.
 		    demotedToPreview.clear();
 		    mediaFailures.clear();
+		    lastRecoveryAt.clear();
 		    loadInventory(true);
 		  };
 		  const onLangChange = (e) => {
@@ -1022,12 +1188,6 @@ window.__ModuleLoader__.load({
 		    applyEffects();
 		    emit();
 		  };
-		  const onPosition = (e) => {
-		    selection.position = POSITIONS.indexOf(e.target.value) >= 0 ? e.target.value : "center";
-		    persistSelection();
-		    applyEffects();
-		    emit();
-		  };
 
 		  if (!sel.loaded) {
 		    return React.createElement("div", { className: "webg-picker" },
@@ -1157,7 +1317,10 @@ window.__ModuleLoader__.load({
 		          value: String(editing.interval),
 		          onChange: (e) => { editing.interval = clampNum(Number(e.target.value), 1, 1440, DEFAULTS.rotationInterval); emit(); },
 		        },
-		        ...INTERVALS.map((minutes) =>
+		        // A persisted interval outside the preset steps (imported groups,
+		        // hand-edited storage) still gets a matching option — otherwise the
+		        // select would silently display the first preset instead of reality.
+		        ...[...new Set([...INTERVALS, editing.interval])].sort((x, y) => x - y).map((minutes) =>
 		          React.createElement("option", { key: minutes, value: String(minutes) }, t.minutes(minutes)),
 		        )),
 		        React.createElement("span", { className: "webg-hint webg-label" }, t.order),
@@ -1255,16 +1418,18 @@ window.__ModuleLoader__.load({
 		        disabled: !sel.rotationEnabled || !sel.rotationGroupId || usableCount < 2,
 		        title: t.intervalTitle,
 		      },
-		      ...INTERVALS.map((minutes) =>
-		        React.createElement("option", { key: minutes, value: String(minutes) }, t.minutes(minutes)),
-		      )),
+		      ...[...new Set([...INTERVALS, group ? group.interval : DEFAULTS.rotationInterval])]
+		        .sort((x, y) => x - y).map((minutes) =>
+		          React.createElement("option", { key: minutes, value: String(minutes) }, t.minutes(minutes)),
+		        )),
 		      !sel.rotationGroupId && React.createElement("span", { className: "webg-hint" }, t.needList),
 		      sel.rotationGroupId && usableCount < 2 && React.createElement("span", { className: "webg-hint" }, t.needTwo),
 		    ),
 		    // ── Effects ──
 		    sel.id && React.createElement(React.Fragment, null,
 		      // Canvas fit only matters for video/still wallpapers — an iframe
-		      // ignores object-fit and always fills its layer.
+		      // ignores object-fit and always fills its layer. Manual crop (drag /
+		      // wheel in the adjust overlay) replaced the old fixed anchor select.
 		      sel.type !== "web" && React.createElement("div", { className: "webg-row webg-fit-row" },
 		        React.createElement("span", { className: "webg-hint webg-label" }, t.fit),
 		        React.createElement("select", {
@@ -1275,19 +1440,19 @@ window.__ModuleLoader__.load({
 		        ...[t.fitCover, t.fitContain, t.fitFill, t.fitNone].map((label, i) =>
 		          React.createElement("option", { key: FIT_MODES[i], value: FIT_MODES[i] }, label),
 		        )),
-		        React.createElement("span", { className: "webg-hint webg-label" }, t.position),
-		        React.createElement("select", {
-		          className: "webg-select webg-position-select",
-		          value: sel.position,
-		          onChange: onPosition,
-		        },
-		        ...[t.posCenter, t.posTop, t.posBottom, t.posLeft, t.posRight].map((label, i) =>
-		          React.createElement("option", { key: POSITIONS[i], value: POSITIONS[i] }, label),
-		        )),
+		        React.createElement("button", {
+		          className: "webg-btn", type: "button", onClick: () => enterAdjust(),
+		          disabled: sel.adjusting,
+		        }, t.adjust),
+		        (sel.zoom !== 1 || sel.offsetX !== 0 || sel.offsetY !== 0) &&
+		          React.createElement("button", {
+		            className: "webg-btn", type: "button", onClick: resetCrop,
+		          }, t.resetCrop),
 		      ),
 		      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.scrim, 0, 90, 5, Math.min(90, 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"),
 		      ),
@@ -1361,18 +1526,43 @@ window.__ModuleLoader__.load({
 		    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);
+		    object-position: center;
 		    display: block;
 		    background: transparent; border: 0;
-		    filter: blur(var(--webg-wallpaper-blur, 0px)) saturate(1.08);
+		    filter: var(--webg-media-filter, none);
+		    /* Manual crop: pan offsets are % of the media box (independent of zoom
+		       because translate is listed before scale), zoom is centered. */
+		    transform: translate(var(--webg-offset-x, 0%), var(--webg-offset-y, 0%)) scale(var(--webg-zoom, 1));
+		    transform-origin: center center;
+		  }
+
+		  /* Crop-adjust overlay: topmost, transparent — only its hint bar is chrome.
+		     The live layer is moved INSIDE, so editing is what-you-see. */
+		  .webg-adjust {
+		    position: fixed; inset: 0; z-index: 2147483000;
+		    cursor: grab; touch-action: none;
+		  }
+		  .webg-adjust:active { cursor: grabbing; }
+		  .webg-adjust .webg-layer { position: absolute; z-index: 0; }
+		  .webg-adjust-bar {
+		    position: absolute; top: 18px; left: 50%; transform: translateX(-50%);
+		    z-index: 1; cursor: default;
+		    display: flex; align-items: center; gap: 12px;
+		    padding: 8px 8px 8px 14px; border-radius: 12px;
+		    background: var(--dsw-alias-bg-overlay, rgba(30, 32, 38, 0.85));
+		    color: var(--dsw-alias-label-primary, inherit);
+		    backdrop-filter: blur(20px);
+		    -webkit-backdrop-filter: blur(20px);
+		    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.18);
+		    font-size: 12px; white-space: nowrap;
 		  }
 
 		  /* 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. */
+		     its frosted materials). display:none at zero blur — no layer, no cost. */
 		  .webg-layer::after {
 		    content: ""; position: absolute; inset: 0; pointer-events: none;
+		    display: var(--webg-noise-display, 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;
@@ -1584,8 +1774,7 @@ window.__ModuleLoader__.load({
 		    font-size: 12px; color: var(--dsw-alias-label-secondary, #888);
 		  }
 		  .webg-card-type {
-		    position: absolute; top: 4px; right: 4px;
-		    padding: 1px 6px; border-radius: 4px;
+		    position: absolute; top: 4px; right: 4px; padding: 1px 6px; border-radius: 4px;
 		    font-size: 10px; line-height: 1.5;
 		    color: #fff; background: rgba(0, 0, 0, 0.5);
 		  }
@@ -1699,8 +1888,14 @@ window.__ModuleLoader__.load({
 		        observer.observe(document.body, { attributes: true, attributeFilter: ["data-ds-dark-theme"] });
 		      }
 		      return () => {
+		        // Stop any in-flight inventory fetch from committing state (and
+		        // re-arming the rotation timer) after teardown began.
+		        disposed = true;
 		        unsubLayers();
 		        unsubEffects();
+		        // Close the crop-adjust overlay if it is open (moves the layer back,
+		        // removes the bar and its listeners) before tearing layers down.
+		        exitAdjust();
 		        if (samplerId !== null) window.clearInterval(samplerId);
 		        if (observer) observer.disconnect();
 		        sampledLuminance = null;

package/lib/core.js

@@ -48,6 +48,15 @@ export function parseKeyValues(text) {
   const src = String(text);
   const n = src.length;
   let i = 0;
+  let depth = 0;
+  const MAX_DEPTH = 100; // pathological nesting degrades, never overflows
+
+  // `__proto__`/`constructor`/`prototype` keys would corrupt (or fabricate
+  // via) the prototype chain through plain assignment — parse and discard.
+  const POISON_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+  const safeAssign = (obj, key, val) => {
+    if (!POISON_KEYS.has(key)) obj[key] = val;
+  };
 
   const skipSpace = () => {
     for (;;) {
@@ -83,6 +92,18 @@ export function parseKeyValues(text) {
   const value = () => {
     skipSpace();
     if (src[i] !== '{') return token();
+    if (++depth > MAX_DEPTH) {
+      // Too deep: consume the block without building it, keep parsing.
+      let d = 1;
+      i++;
+      while (i < n && d > 0) {
+        if (src[i] === '{') d++;
+        else if (src[i] === '}') d--;
+        i++;
+      }
+      depth--;
+      return null;
+    }
     i++;
     const obj = {};
     for (;;) {
@@ -90,8 +111,9 @@ export function parseKeyValues(text) {
       if (i >= n) break;
       if (src[i] === '}') { i++; break; }
       const key = token();
-      obj[key] = value();
+      safeAssign(obj, key, value());
     }
+    depth--;
     return obj;
   };
 
@@ -101,7 +123,7 @@ export function parseKeyValues(text) {
     if (i >= n) break;
     const key = token();
     if (!key) { i++; continue; }
-    root[key] = value();
+    safeAssign(root, key, value());
   }
   return root;
 }
@@ -446,7 +468,8 @@ export function pathKey(file) {
  * to an enumerated wallpaper id. Strategy order:
  *   1. exact normalized path match against enumerated main files,
  *   2. workshop url fragment `…/431960/<projectId>/…`,
- *   3. trailing project-folder name (covers install-relative entries).
+ *   3. trailing project-folder name (covers install-relative entries),
+ *   4. bare workshop id.
  * @param {string} item
  * @param {Map<string, string>} byPath pathKey(fileAbs) → id
  * @param {Map<string, unknown>} byId id → project
@@ -459,6 +482,7 @@ export function resolvePlaylistItem(item, byPath, byId) {
   if (workshop && byId.has(workshop[1])) return workshop[1];
   const folder = /[\\/]([^\\/]+)[\\/][^\\/]+$/i.exec(item);
   if (folder && byId.has(folder[1])) return folder[1];
+  if (typeof item === 'string' && byId.has(item)) return item; // bare id
   return null;
 }
 
@@ -551,8 +575,11 @@ export async function buildInventoryFrom(discovery = {}, io = {}) {
 
   const wallpapers = [];
   for (const p of projects) {
-    const portable = PORTABLE_KINDS.includes(p.type);
-    const hasMedia = portable && await exists(p.fileAbs);
+    // Renderable kinds ONLY: scene/application wallpapers are .pkg scene
+    // packages no browser can render, and their preview stills are a
+    // degraded experience — skip them instead of offering them.
+    if (!PORTABLE_KINDS.includes(p.type)) continue;
+    const hasMedia = 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` })
@@ -566,6 +593,8 @@ export async function buildInventoryFrom(discovery = {}, io = {}) {
       type: p.type,
       playable: hasMedia && Boolean(mediaToken),
       media: hasMedia && mediaToken ? `${base}/media/${mediaToken}` : null,
+      // The preview stays in the payload even though stills are never
+      // selected: it is the decode-failure fallback for playable entries.
       preview: hasPreview && previewToken ? `${base}/preview/${previewToken}` : null,
     });
   }
@@ -583,7 +612,11 @@ export async function buildInventoryFrom(discovery = {}, io = {}) {
     const seen = new Set();
     for (const item of playlist.items) {
       const id = resolvePlaylistItem(item, byPath, byId);
-      if (id && !seen.has(id)) { seen.add(id); ids.push(id); }
+      // Only ids present IN THE PAYLOAD: a scene/application item resolves
+      // to an enumerated project but is filtered from wallpapers[] — keeping
+      // it would hand the client a dangling id it cannot render or look up.
+      // Such items count as unresolved (they are, for our purposes).
+      if (id && playableIds.has(id) && !seen.has(id)) { seen.add(id); ids.push(id); }
     }
     return {
       id: `pl-${index}`,

package/lib/index.js

@@ -44,7 +44,7 @@ import {
 } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 
 import * as core from './core.js';
 
@@ -155,14 +155,22 @@ export function createRouteRegistrar(webServer, opts = {}) {
   // ── Inventory (cached) ──────────────────────────────────────────────────
   let cache = null; // { at: number, payload: object }
   let discoveryCache = null; // { at: number, value: object }
+  let discovering = null; // in-flight discovery (cold-start dedupe)
   let building = null; // in-flight build promise (request coalescing)
 
   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;
+    // Concurrent callers (registration warm-up + first request) share ONE
+    // discovery run instead of racing reg.exe twice at cold start.
+    if (discovering && !force) return discovering;
+    discovering = discoverFn()
+      .then((value) => {
+        discoveryCache = { at: Date.now(), value };
+        return value;
+      })
+      .finally(() => { if (!force) discovering = null; });
+    return discovering;
   }
 
   async function buildInventory(force) {
@@ -180,8 +188,14 @@ export function createRouteRegistrar(webServer, opts = {}) {
     if (!force && cache && Date.now() - cache.at < inventoryTtlMs) {
       return Promise.resolve(cache.payload);
     }
-    // Coalesce concurrent builds (double-clicked 刷新, parallel clients).
-    if (building) return building;
+    // Coalesce concurrent NON-forced builds (double-clicked 刷新 within the
+    // same tick, parallel clients). A forced refresh must never be folded
+    // into a non-forced in-flight build — the whole point of ?refresh=1 is
+    // the remint, so it waits for the current build and then rebuilds.
+    if (building) {
+      if (!force) return building;
+      return building.catch(() => {}).then(() => getInventory(true));
+    }
     building = buildInventory(force)
       .then((payload) => { cache = { at: Date.now(), payload }; return payload; })
       .finally(() => { building = null; });
@@ -207,10 +221,18 @@ export function createRouteRegistrar(webServer, opts = {}) {
         res.end();
         return;
       }
-      res.setHeader('Content-Type', core.mimeFor(absPath));
+      const mime = core.mimeFor(absPath);
+      res.setHeader('Content-Type', mime);
       res.setHeader('Accept-Ranges', 'bytes');
       res.setHeader('Cache-Control', 'no-store');
       res.setHeader('X-Content-Type-Options', 'nosniff');
+      if (mime === 'text/html' || mime === 'image/svg+xml') {
+        // Script-capable documents (web wallpapers, SVG previews) get a
+        // sandboxed CSP even on direct top-level navigation, so they can
+        // never execute against the DSH origin. The client's iframe sandbox
+        // already covers embedding; this is the server-side backstop.
+        res.setHeader('Content-Security-Policy', 'sandbox');
+      }
 
       const range = core.parseRangeHeader(req.headers.range, st.size);
       if (range && range.error) {
@@ -237,6 +259,16 @@ export function createRouteRegistrar(webServer, opts = {}) {
       // leave the already-announced Content-Length unsatisfied and the
       // client hanging — destroy the response instead.
       stream.on('error', () => { res.destroy(); });
+      // A file that SHRANK between stat and open streams fewer bytes than
+      // the announced Content-Length without any open error — count what
+      // actually went out and tear the response down on a short read so the
+      // client sees a retryable network failure, not a silent truncation.
+      const expected = range ? range.end - range.start + 1 : st.size;
+      let sent = 0;
+      stream.on('data', (chunk) => { sent += chunk.length; });
+      stream.on('end', () => {
+        if (sent !== expected) res.destroy();
+      });
       stream.pipe(res);
     }).catch(() => {
       res.statusCode = 404;
@@ -245,6 +277,27 @@ export function createRouteRegistrar(webServer, opts = {}) {
     });
   }
 
+  /**
+   * Real-path containment check (symlink defense). The lexical
+   * isInsideDir() passes above reject `..`-style escapes, but a symlink
+   * placed inside a wallpaper dir pointing outside would sail through
+   * lexically and be followed at open time. Resolve BOTH sides with
+   * realpath and re-check: a symlinked target resolves outside the real
+   * root and is refused. Resolves null when the path does not exist.
+   */
+  const realRootCache = new Map(); // token → realpath(root) | null
+  async function realPathWithin(entry, candidateAbs) {
+    let rootReal = realRootCache.get(entry.key || entry.abs);
+    if (rootReal === undefined) {
+      rootReal = await fsp.realpath(entry.rootDir || dirname(entry.abs)).catch(() => null);
+      realRootCache.set(entry.key || entry.abs, rootReal);
+    }
+    if (!rootReal) return null;
+    const realAbs = await fsp.realpath(candidateAbs).catch(() => null);
+    if (!realAbs || !core.isInsideDir(rootReal, realAbs)) return null;
+    return realAbs;
+  }
+
   // ── Routes ──────────────────────────────────────────────────────────────
   const disposers = [];
 
@@ -253,14 +306,24 @@ export function createRouteRegistrar(webServer, opts = {}) {
     path: `${BASE}/inventory`,
     handler: (req, res) => {
       if (req.method !== 'GET' && req.method !== 'HEAD') {
+        res.setHeader('Allow', 'GET, HEAD');
         sendJson(req, res, 405, { error: 'method not allowed' });
         return;
       }
-      const url = new URL(req.url || '/', 'http://x');
+      let url;
+      try {
+        url = new URL(req.url || '/', 'http://x');
+      } catch {
+        sendJson(req, res, 400, { error: 'bad request' });
+        return;
+      }
       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) });
+          // Loopback-only, but the raw message can carry absolute paths —
+          // genericise for the wire, keep detail in the server log.
+          console.error('[we-background] inventory build failed:', err && err.stack || err);
+          sendJson(req, res, 500, { error: 'inventory build failed' });
         });
     },
   }));
@@ -272,6 +335,7 @@ export function createRouteRegistrar(webServer, opts = {}) {
       path: `${BASE}/${seg}`,
       handler: (req, res) => {
         if (req.method !== 'GET' && req.method !== 'HEAD') {
+          res.setHeader('Allow', 'GET, HEAD');
           sendJson(req, res, 405, { error: 'method not allowed' });
           return;
         }
@@ -324,7 +388,17 @@ export function createRouteRegistrar(webServer, opts = {}) {
             return;
           }
         }
-        serveFile(abs, req, res);
+        // Symlink backstop: serve only what realpath still keeps inside the
+        // entry's real root (404 — indistinguishable from a vanished file).
+        realPathWithin(entry, abs).then((real) => {
+          if (!real) {
+            res.statusCode = 404;
+            res.setHeader('Content-Length', '0');
+            res.end();
+            return;
+          }
+          serveFile(real, req, res);
+        });
       },
     }));
   }

package/lib/types/index.d.ts

@@ -4,10 +4,14 @@
  * mirrored on the default export.
  */
 
+/**
+ * One inventory entry. Scene/application wallpapers are filtered out at the
+ * source — the wire only ever carries the browser-renderable kinds.
+ */
 export interface WallpaperSummary {
   id: string;
   title: string;
-  type: 'scene' | 'video' | 'web' | 'application';
+  type: 'video' | 'web';
   playable: boolean;
   media: string | null;
   preview: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wallpaper-engine-dsh",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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",