wallpaper-engine-dsh 0.1.6 → 0.1.8

package/README.md

@@ -9,8 +9,9 @@ A DSH bundle that turns your local **Wallpaper Engine** library into the live ba
 - **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).
 - **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, border contrast, and glass frosting, all instant and persisted.
-- **Canvas fit** — cover/contain/stretch/original sizing plus five-way alignment for video and still wallpapers.
+- **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.
+- **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.
@@ -34,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.
@@ -49,7 +50,7 @@ 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 the browser cannot decode falls back to the wallpaper's preview image. Scene and application wallpapers can only show their workshop preview — the bundle reads each preview's pixel size and presents low-resolution ones as sharp centered art over a blurred copy of themselves, instead of a mushy fullscreen stretch.
 
 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.
 

package/README.zh.md

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

package/lib/client.js

@@ -19,6 +19,12 @@ window.__ModuleLoader__.load({
 		/** Below this FPS the picker shows a performance hint. */
 		const LOW_FPS = 24;
 
+		/**
+		 * Below this preview width a fullscreen cover render is pure upscale mush —
+		 * present as ambient (sharp contain over a blurred copy of itself) instead.
+		 */
+		const LOW_RES_PREVIEW_PX = 1200;
+
 		// Respect the OS "reduce motion" preference: start paused rather than
 		// autoplaying a video loop at someone who asked for less motion.
 		const REDUCED_MOTION = typeof window !== "undefined" &&
@@ -79,6 +85,8 @@ window.__ModuleLoader__.load({
 		    glass: "玻璃",
 		    pauseOnHidden: "页面隐藏时暂停",
 		    pauseOnBattery: "低电量时暂停",
+		    autoScrim: "智能可视",
+		    autoScrimTitle: "采样壁纸亮度,过亮或过暗时自动加强遮罩,保证文字可读",
 		    fpsTitle: "页面当前渲染帧率",
 		    lowFpsHint: "帧率偏低,可尝试暂停视频、增大壁纸模糊或换用静态壁纸",
 		    language: "语言",
@@ -88,12 +96,12 @@ window.__ModuleLoader__.load({
 		    fitContain: "适应",
 		    fitFill: "拉伸",
 		    fitNone: "原始",
-		    position: "对齐",
-		    posCenter: "居中",
-		    posTop: "顶部",
-		    posBottom: "底部",
-		    posLeft: "居左",
-		    posRight: "居右",
+		    adjust: "调整画面",
+		    adjustDone: "完成",
+		    adjustHint: "拖动平移 · 滚轮缩放 · Esc 或点「完成」退出",
+		    resetCrop: "重置裁剪",
+		    ambientNote: "预览分辨率低,已氛围化显示",
+		    lowResBadge: "低清",
 		    statusGroup: (name, total, usable, interval, order) =>
 		      "列表「" + name + "」:" + total + " 项 · " + usable + " 可用 · 每 " + interval + " 分钟 · " + order,
 		    statusUsable: (n) => n + " 张可用壁纸",
@@ -157,6 +165,8 @@ window.__ModuleLoader__.load({
 		    glass: "Glass",
 		    pauseOnHidden: "Pause when tab hidden",
 		    pauseOnBattery: "Pause on low battery",
+		    autoScrim: "Smart veil",
+		    autoScrimTitle: "Samples wallpaper brightness and strengthens the veil when needed so text stays readable",
 		    fpsTitle: "Current page frame rate",
 		    lowFpsHint: "Low frame rate — try pausing the video, raising wallpaper blur, or using a still wallpaper",
 		    language: "Language",
@@ -166,12 +176,12 @@ 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",
+		    ambientNote: "Low-res preview — ambient fill",
+		    lowResBadge: "Low-res",
 		    statusGroup: (name, total, usable, interval, order) =>
 		      "List \"" + name + "\": " + total + " items · " + usable + " usable · every " + interval + " min · " + order,
 		    statusUsable: (n) => n + " usable wallpapers",
@@ -218,13 +228,15 @@ window.__ModuleLoader__.load({
 		  rotationSeeded: false,
 		  pauseOnHidden: true,
 		  pauseOnBattery: true,
+		  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) {
@@ -268,9 +280,12 @@ window.__ModuleLoader__.load({
 		      rotationSeeded: o.rotationSeeded === true,
 		      pauseOnHidden: o.pauseOnHidden !== false,
 		      pauseOnBattery: o.pauseOnBattery !== false,
+		      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 };
@@ -282,6 +297,8 @@ window.__ModuleLoader__.load({
 		  ...readPersisted(),
 		  url: null,
 		  type: null,
+		  previewW: null, // pixel width of the still being shown (ambient decisions)
+		  adjusting: false, // crop-adjust overlay open (not persisted)
 		  playing: !REDUCED_MOTION,
 		  loading: false,
 		  rotationTimer: null,
@@ -319,9 +336,12 @@ window.__ModuleLoader__.load({
 		      rotationSeeded: selection.rotationSeeded,
 		      pauseOnHidden: selection.pauseOnHidden,
 		      pauseOnBattery: selection.pauseOnBattery,
+		      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 */ }
 		}
@@ -575,6 +595,7 @@ window.__ModuleLoader__.load({
 		}
 
 		function applySelection(id) {
+		  if (selection.adjusting) exitAdjust();
 		  selection.id = id || "";
 		  persistSelection();
 		  const w = selection.id
@@ -583,14 +604,17 @@ window.__ModuleLoader__.load({
 		  if (isPlayable(w) && !demotedToPreview.has(selection.id)) {
 		    selection.url = w.media;
 		    selection.type = w.type; // "video" | "web"
+		    selection.previewW = null;
 		  } 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";
+		    selection.previewW = typeof w.previewW === "number" ? w.previewW : null;
 		  } else {
 		    selection.url = null;
 		    selection.type = null;
+		    selection.previewW = null;
 		  }
 		  syncRotationTimer();
 		  emit();
@@ -659,7 +683,42 @@ window.__ModuleLoader__.load({
 		    media.draggable = false;
 		    media.setAttribute("decoding", "async");
 		    media.className = "webg-media";
+		    // Low-resolution previews (many workshop scenes ship 256–500px thumbs)
+		    // look terrible stretched fullscreen under cover. Present them like
+		    // music-app artwork instead: the image at its natural sharpness
+		    // (contain), over a heavily blurred full-bleed copy of itself.
+		    if (sel.fit === "cover" && typeof sel.previewW === "number" &&
+		        sel.previewW > 0 && sel.previewW < LOW_RES_PREVIEW_PX) {
+		      const wrap = document.createElement("div");
+		      wrap.className = "webg-ambient";
+		      const bg = document.createElement("img");
+		      bg.src = sel.url;
+		      bg.alt = "";
+		      bg.draggable = false;
+		      bg.className = "webg-ambient-bg";
+		      wrap.appendChild(bg);
+		      media.classList.add("webg-ambient-fg");
+		      wrap.appendChild(media);
+		      attachStillSampling(media);
+		      attachMediaError(media, sel);
+		      return wrap;
+		    }
 		  }
+		  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;
@@ -678,7 +737,120 @@ window.__ModuleLoader__.load({
 		      applySelection(id);
 		    }
 		  });
-		  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;
+		    const w = overlay.clientWidth || 1;
+		    const h = overlay.clientHeight || 1;
+		    // 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();
+		  };
+		  const onWheel = (e) => {
+		    if (typeof e.preventDefault === "function") e.preventDefault();
+		    const next = clampNum(selection.zoom * Math.exp(-(e.deltaY || 0) * 0.0012),
+		      0.25, 4, selection.zoom);
+		    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("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("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();
+		}
+
+		function isAmbientActive(sel) {
+		  return sel.type === "image" && sel.fit === "cover" &&
+		    typeof sel.previewW === "number" && sel.previewW > 0 &&
+		    sel.previewW < LOW_RES_PREVIEW_PX;
 		}
 
 		// Crossfade/clear leave timers: tracked so dispose can cancel them instead of
@@ -765,27 +937,82 @@ window.__ModuleLoader__.load({
 		}
 
 		// ── Effect application: push the knobs into CSS variables ───────────────────
+		// Wallpaper luminance sampled from the live media (null until the first
+		// sample; iframes of web wallpapers can never be sampled — opaque origin).
+		let sampledLuminance = null;
+		let sampleCanvas = null;
+
+		/** Average Rec.601 luminance (0..1) of the current video/img, or null. */
+		function sampleWallpaperLuminance() {
+		  if (typeof document === "undefined") return;
+		  const layer = document.getElementById(LAYER_ID);
+		  const media = layer && (layer.querySelector("video") || layer.querySelector("img"));
+		  if (!media) { sampledLuminance = null; return; }
+		  try {
+		    if (!sampleCanvas) {
+		      const c = document.createElement("canvas");
+		      if (typeof c.getContext !== "function") return; // no canvas → no sampling
+		      c.width = 16; c.height = 16;
+		      sampleCanvas = c;
+		    }
+		    const g = sampleCanvas.getContext("2d", { willReadFrequently: true });
+		    g.drawImage(media, 0, 0, 16, 16);
+		    const d = g.getImageData(0, 0, 16, 16).data;
+		    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];
+		    }
+		    sampledLuminance = sum / (d.length / 4) / 255;
+		  } catch { /* frame not ready / unreadable → keep the previous sample */ }
+		}
+
 		function applyEffects() {
 		  const s = document.body.style;
-		  s.setProperty("--webg-scrim-color", "rgba(0,0,0," + selection.scrim + ")");
+		  // The veil OPPOSES the text colour: dark theme (light text) darkens bright
+		  // wallpapers, light theme (dark text) brightens dark ones — either way the
+		  // text side wins. This is what makes ANY wallpaper survivable.
+		  const dark = Boolean(document.body.hasAttribute && document.body.hasAttribute("data-ds-dark-theme"));
+		  let alpha = selection.scrim;
+		  if (selection.autoScrim && sampledLuminance !== null) {
+		    // Distance of the wallpaper's brightness from the "comfortable middle"
+		    // towards the text colour's weakness, mapped to a veil-alpha floor.
+		    const need = dark
+		      ? Math.min(0.55, Math.max(0, sampledLuminance - 0.5))
+		      : Math.min(0.55, Math.max(0, 0.5 - sampledLuminance));
+		    alpha = Math.max(alpha, Math.round(need * 1000) / 1000);
+		  }
+		  const veilColor = "rgba(" + (dark ? "0,0,0" : "255,255,255") + "," + alpha + ")";
+		  s.setProperty("--webg-scrim-color", veilColor);
 		  s.setProperty("--webg-border-alpha", String(selection.border));
 		  s.setProperty("--webg-blur", selection.blur + "px");
 		  // The glass "colour melt" scales with blur radius: 0 blur → no melt.
 		  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.
 		  const scrim = document.getElementById(SCRIM_ID);
-		  if (scrim) scrim.style.background = "rgba(0,0,0," + selection.scrim + ")";
+		  if (scrim) scrim.style.background = veilColor;
 		  if (document.body && document.body.offsetHeight !== undefined) {
 		    void document.body.offsetHeight;
 		  }
@@ -799,9 +1026,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 = "";
 		}
@@ -862,6 +1093,8 @@ window.__ModuleLoader__.load({
 		      })
 		    : React.createElement("span", { className: "webg-card-placeholder" }, t.noPreview),
 		  React.createElement("span", { className: "webg-card-type" }, typeBadge(w, t)),
+		  (typeof w.previewW === "number" && w.previewW > 0 && w.previewW < LOW_RES_PREVIEW_PX) &&
+		    React.createElement("span", { className: "webg-card-lowres" }, t.lowResBadge),
 		  React.createElement("span", { className: "webg-card-title" }, w.title),
 		  );
 		}
@@ -947,6 +1180,12 @@ window.__ModuleLoader__.load({
 		    persistSelection();
 		    emit();
 		  };
+		  const onToggleAutoScrim = () => {
+		    selection.autoScrim = !selection.autoScrim;
+		    persistSelection();
+		    applyEffects();
+		    emit();
+		  };
 
 		  const onScrim = (pct) => { selection.scrim = pct / 100; persistSelection(); applyEffects(); emit(); };
 		  const onBorder = (pct) => { selection.border = pct / 100; persistSelection(); applyEffects(); emit(); };
@@ -958,12 +1197,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" },
@@ -1200,7 +1433,8 @@ window.__ModuleLoader__.load({
 		    // ── 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", {
@@ -1211,15 +1445,16 @@ 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),
+		        isAmbientActive(sel) &&
+		          React.createElement("span", { className: "webg-hint" }, t.ambientNote),
 		      ),
 		      React.createElement("div", { className: "webg-effects" },
 		        SliderRow(t.wallpaperBlur, 0, 60, 1, sel.wallpaperBlur, onWallpaperBlur, sel.wallpaperBlur + "px"),
@@ -1242,6 +1477,12 @@ window.__ModuleLoader__.load({
 		        }),
 		        t.pauseOnBattery,
 		      ),
+		      React.createElement("label", { className: "webg-toggle", title: t.autoScrimTitle },
+		        React.createElement("input", {
+		          type: "checkbox", checked: sel.autoScrim, onChange: onToggleAutoScrim,
+		        }),
+		        t.autoScrim,
+		      ),
 		      sel.fps !== null && React.createElement("span", {
 		        className: "webg-hint webg-fps" + (sel.fps < LOW_FPS ? " webg-fps--low" : ""),
 		        title: t.fpsTitle,
@@ -1291,18 +1532,63 @@ 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;
+		  }
+
+		  /* Ambient presentation for low-resolution stills: the sharp image (fg,
+		     contain) floats over a heavily blurred full-bleed copy of itself (bg).
+		     The fg keeps the user's wallpaper-blur/crop; the bg has its own fixed
+		     blur with its own overscan, so its fringe never shows. */
+		  .webg-ambient {
+		    position: absolute;
+		    inset: calc(-1 * var(--webg-wallpaper-blur, 0px));
+		    overflow: hidden;
+		  }
+		  .webg-ambient-bg {
+		    position: absolute; inset: -64px;
+		    width: calc(100% + 128px); height: calc(100% + 128px);
+		    object-fit: cover; display: block;
+		    filter: blur(48px) saturate(1.25) brightness(0.92);
+		  }
+		  .webg-ambient .webg-media {
+		    inset: 0; width: 100%; height: 100%;
+		    object-fit: contain;
+		  }
+
+		  /* 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;
@@ -1514,8 +1800,12 @@ 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);
+		  }
+		  .webg-card-lowres {
+		    position: absolute; top: 4px; left: 4px; padding: 1px 6px; border-radius: 4px;
 		    font-size: 10px; line-height: 1.5;
 		    color: #fff; background: rgba(0, 0, 0, 0.5);
 		  }
@@ -1612,9 +1902,31 @@ window.__ModuleLoader__.load({
 		      const unsubEffects = subscribe(applyEffects);
 		      syncLayers();
 		      applyEffects();
+		      // Luminance sampler: re-reads the wallpaper periodically so a bright
+		      // scene arriving mid-video re-raises the veil. (rAF-free: 2.5 s is
+		      // plenty for legibility, and an idle timer costs ~nothing.)
+		      let samplerId = null;
+		      if (typeof window !== "undefined" && typeof window.setInterval === "function") {
+		        samplerId = window.setInterval(() => {
+		          sampleWallpaperLuminance();
+		          applyEffects();
+		        }, 2500);
+		      }
+		      // A theme switch flips the veil colour immediately (black ↔ white).
+		      let observer = null;
+		      if (typeof MutationObserver === "function") {
+		        observer = new MutationObserver(() => applyEffects());
+		        observer.observe(document.body, { attributes: true, attributeFilter: ["data-ds-dark-theme"] });
+		      }
 		      return () => {
 		        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;
 		        clearRotationTimer();
 		        // Cancel pending crossfade/clear timers so they never fire on
 		        // torn-down nodes after dispose.

package/lib/core.js

@@ -25,6 +25,59 @@ export const WE_APPID = '431960';
 /** Wallpaper kinds WE can declare. */
 export const KINDS = Object.freeze(['scene', 'video', 'web', 'application']);
 
+// ── 6. Image dimension sniffing ─────────────────────────────────────────────
+
+/**
+ * Read pixel dimensions from an image's header bytes (JPEG/PNG/GIF/WebP).
+ * Used to tell the client how sharp a scene/application preview really is —
+ * workshop previews range from 256px thumbnails to full renders, and the UI
+ * presents low-resolution ones differently.
+ *
+ * Header-only: reads at most 64 KiB, never decodes pixels. Returns
+ * `{ w, h }` or null for unrecognized/truncated data.
+ *
+ * @param {Buffer|Uint8Array} b
+ * @returns {{ w: number, h: number } | null}
+ */
+export function sniffImageSize(b) {
+  if (!b || b.length < 10) return null; // GIF needs 10; other formats check their own reach
+  // PNG: 8-byte signature, then IHDR with width/height big-endian at 16/20.
+  if (b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4E && b[3] === 0x47) {
+    if (b.length < 24) return null;
+    return { w: b.readUInt32BE(16), h: b.readUInt32BE(20) };
+  }
+  // GIF: logical screen dimensions little-endian at 6/8.
+  const sig6 = b.toString('latin1', 0, 6);
+  if (sig6 === 'GIF87a' || sig6 === 'GIF89a') {
+    return { w: b.readUInt16LE(6), h: b.readUInt16LE(8) };
+  }
+  // JPEG: walk markers to the first start-of-frame segment.
+  if (b[0] === 0xFF && b[1] === 0xD8) {
+    let i = 2;
+    while (i + 9 < b.length) {
+      if (b[i] !== 0xFF) { i++; continue; }
+      const marker = b[i + 1];
+      if (marker >= 0xC0 && marker <= 0xCF && marker !== 0xC4 && marker !== 0xC8 && marker !== 0xCC) {
+        return { w: b.readUInt16BE(i + 7), h: b.readUInt16BE(i + 5) };
+      }
+      i += 2 + b.readUInt16BE(i + 2);
+    }
+    return null;
+  }
+  // WebP: RIFF container; VP8X carries canvas size minus one, uint24 LE.
+  if (b.toString('latin1', 0, 4) === 'RIFF' && b.toString('latin1', 8, 12) === 'WEBP' &&
+      b.toString('latin1', 12, 16) === 'VP8X' && b.length >= 30) {
+    return {
+      w: 1 + b[24] + (b[25] << 8) + (b[26] << 16),
+      h: 1 + b[27] + (b[28] << 8) + (b[29] << 16),
+    };
+  }
+  return null;
+}
+
+/** Kinds whose only browser-renderable asset is the preview image. */
+const PREVIEW_ONLY_KINDS = new Set(['scene', 'application']);
+
 /** Kinds this bundle can render in a browser. */
 export const PORTABLE_KINDS = Object.freeze(['video', 'web']);
 
@@ -560,6 +613,15 @@ export async function buildInventoryFrom(discovery = {}, io = {}) {
     const previewToken = hasPreview
       ? mint({ abs: p.previewAbs, rootDir: null, key: `${p.id}:preview` })
       : null;
+    // Preview pixel size matters for scene/application wallpapers: the
+    // preview is ALL the browser can show, so the client needs to know how
+    // sharp it is. Sniff only for preview-only kinds (videos don't care).
+    let previewSize = null;
+    if (hasPreview && PREVIEW_ONLY_KINDS.has(p.type) &&
+        typeof io.readBuffer === 'function') {
+      try { previewSize = sniffImageSize(await io.readBuffer(p.previewAbs, 65536)); }
+      catch { previewSize = null; }
+    }
     wallpapers.push({
       id: p.id,
       title: p.title,
@@ -567,6 +629,8 @@ export async function buildInventoryFrom(discovery = {}, io = {}) {
       playable: hasMedia && Boolean(mediaToken),
       media: hasMedia && mediaToken ? `${base}/media/${mediaToken}` : null,
       preview: hasPreview && previewToken ? `${base}/preview/${previewToken}` : null,
+      previewW: previewSize ? previewSize.w : null,
+      previewH: previewSize ? previewSize.h : null,
     });
   }
   const playableIds = new Set(wallpapers.filter((w) => w.playable).map((w) => w.id));

package/lib/index.js

@@ -61,6 +61,15 @@ const asyncIo = {
   readFileSync: (p, encoding) => fsp.readFile(p, encoding),
   readdirSync: (p) => fsp.readdir(p),
   statSync: (p) => fsp.stat(p),
+  // Header-only binary read for the image dimension sniffer (64 KiB cap).
+  readBuffer: async (p, max) => {
+    const fh = await fsp.open(p, 'r');
+    try {
+      const buf = Buffer.alloc(Math.min(max, 65536));
+      const { bytesRead } = await fh.read(buf, 0, buf.length, 0);
+      return buf.subarray(0, bytesRead);
+    } finally { await fh.close(); }
+  },
 };
 
 /** Steam root recorded by the Windows installer; null elsewhere/on failure. */

package/package.json

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