wallpaper-engine-dsh 1.0.4 → 1.0.5

package/README.md

@@ -10,7 +10,7 @@ A DSH bundle that turns your local **Wallpaper Engine** library into the live ba
 
 **Legibility on any wallpaper.** Text stays readable by construction, not by luck. The veil always opposes the text colour — black in the dark theme, white in the light theme — so neither a pitch-black nor a pure-white wallpaper can swallow the UI. On top of that, a Smart veil samples the wallpaper's brightness every few seconds and automatically strengthens the veil when a scene drifts too bright (or too dark) for the current theme; it also strengthens the border contrast and the glass frosting on the same evidence. Dropdowns, menus, and dialogs sit on DSH's opaque surfaces and are never affected.
 
-**Manual framing.** Pick a base layout — Cover, Contain, Stretch, or Original — then frame the shot yourself. **Adjust** opens the live wallpaper fullscreen: scroll to zoom in (up to 4×), drag to pan within the zoomed framing — the crop is clamped so the image always fills the screen with no exposed edges. Esc or Done finishes, the framing persists, and **Reset crop** restores the default in one click. Web wallpapers take the zoom/pan framing too; the base-layout select applies to video and stills and hides itself for web.
+**Manual framing.** Pick a base layout — Cover, Contain, Stretch, Original, or Free — then frame the shot yourself. **Adjust** opens the live wallpaper fullscreen: scroll to zoom, drag to pan. In the first four layouts the crop is clamped so the image always fills the screen with no exposed edges; **Free** places the wallpaper at natural size on a black canvas where it can be dragged anywhere and zoomed from 0.1× to 4×, with just enough kept on screen that it can never be dragged out of sight. Esc or Done finishes, the framing persists, and **Reset crop** restores the default in one click. Web wallpapers take the same select and the same zoom/pan framing — the transform applies to the iframe directly.
 
 **Four live sliders.** Wallpaper blur, Scrim, Borders, and Glass — every change lands instantly and persists. Blur renders in place: composition, layout, and crop stay identical at every blur level, and within one blur radius of the screen edge the picture fades softly into the veil beneath the UI chrome. A whisper of dither noise keeps smooth gradients band-free; at zero blur the media bypasses the filter pipeline entirely for bit-exact pixels.
 

package/README.zh.md

@@ -10,7 +10,7 @@
 
 **任何壁纸上文字都可读。** 遮罩颜色始终与文字颜色相反:深色主题用黑色遮罩,浅色主题用白色遮罩,因此过亮或过暗的壁纸都不会盖住文字。在此基础上,「智能可视」每隔几秒采样一次壁纸亮度,亮度过高或过低时自动加强遮罩。下拉菜单、弹窗等浮层显示在 DSH 原生的不透明表面上,不受影响。
 
-**手动取景。** 先选基础排布(填充、适应、拉伸、原始),再手动调整画面:点「调整画面」将壁纸全屏展开,滚轮放大(最高 4×),拖动在放大后的画面内平移。裁剪范围经过限制,画面始终铺满屏幕,不露出边缘。按 Esc 或点「完成」退出,取景设置会保存,「重置裁剪」可一键恢复默认。网页壁纸同样支持缩放与平移;排布下拉只对视频与静态图生效,网页壁纸时自动隐藏。
+**手动取景。** 先选基础排布(填充、适应、拉伸、原始、自由),再手动调整画面:点「调整画面」将壁纸全屏展开,滚轮缩放,拖动平移。前四种排布下裁剪范围经过限制,画面始终铺满屏幕,不露出边缘;「自由」把壁纸按原始大小放在黑色画布上,可拖动到任意位置,缩放范围 0.1–4×,并始终保留一小块在屏幕内,不会拖丢。按 Esc 或点「完成」退出,取景设置会保存,「重置裁剪」可一键恢复默认。网页壁纸使用相同的排布下拉与缩放/平移取景(变换直接作用于 iframe)。
 
 **四个实时滑杆。** 壁纸模糊、暗化、边框、玻璃,每一步调节立即生效并保存。模糊在原位渲染:任意模糊度下,画面的比例、排布与取景完全一致;屏幕边缘一个模糊半径内的画面向遮罩过渡,被界面边饰覆盖,通常不可见。模糊时叠加轻微噪声,消除渐变色带;模糊为零时媒体完全绕过滤镜管线,像素保持不变。
 

package/lib/client.js

@@ -91,6 +91,7 @@ window.__ModuleLoader__.load({
 		    fitContain: "适应",
 		    fitFill: "拉伸",
 		    fitNone: "原始",
+		    fitFree: "自由",
 		    adjust: "调整画面",
 		    adjustDone: "完成",
 		    adjustHint: "拖动平移 · 滚轮缩放 · Esc 或点「完成」退出",
@@ -168,6 +169,7 @@ window.__ModuleLoader__.load({
 		    fitContain: "Contain",
 		    fitFill: "Stretch",
 		    fitNone: "Original",
+		    fitFree: "Free",
 		    adjust: "Adjust",
 		    adjustDone: "Done",
 		    adjustHint: "Drag to pan · wheel to zoom · Esc or Done to exit",
@@ -226,7 +228,7 @@ window.__ModuleLoader__.load({
 		  offsetY: 0,
 		};
 
-		const FIT_MODES = ["cover", "contain", "fill", "none"];
+		const FIT_MODES = ["cover", "contain", "fill", "none", "free"];
 
 		// ── Persisted selection ─────────────────────────────────────────────────────
 		function clampNum(v, lo, hi, fallback) {
@@ -273,11 +275,12 @@ window.__ModuleLoader__.load({
 		      autoScrim: o.autoScrim !== false,
 		      lang: o.lang === "zh" || o.lang === "en" ? o.lang : "auto",
 		      fit: FIT_MODES.indexOf(o.fit) >= 0 ? o.fit : DEFAULTS.fit,
-		      // Older builds could persist zoom < 1 / unclamped pans — clampCrop()
-		      // at store creation re-seats both into the gap-free envelope.
-		      zoom: clampNum(o.zoom, 0.25, 4, DEFAULTS.zoom),
-		      offsetX: clampNum(o.offsetX, -200, 200, DEFAULTS.offsetX),
-		      offsetY: clampNum(o.offsetY, -200, 200, DEFAULTS.offsetY),
+		      // Older builds could persist unclamped crops — clampCrop() at store
+		      // creation re-seats both into the envelope the CURRENT fit mode
+		      // allows (free: zoom ≥ 0.1 with keep-visible pans; others: gap-free).
+		      zoom: clampNum(o.zoom, 0.1, 4, DEFAULTS.zoom),
+		      offsetX: clampNum(o.offsetX, -300, 300, DEFAULTS.offsetX),
+		      offsetY: clampNum(o.offsetY, -300, 300, DEFAULTS.offsetY),
 		    };
 		  } catch {
 		    return { id: "", ...DEFAULTS };
@@ -302,8 +305,8 @@ window.__ModuleLoader__.load({
 		  inventory: { installDir: null, wallpapers: [], total: 0, portableCount: 0, playlists: [], error: null },
 		  loaded: false,
 		};
-		// Older builds allowed zoom < 1 and unclamped pans — re-seat any persisted
-		// crop into the gap-free envelope before the first render.
+		// Re-seat any persisted crop into the envelope the persisted fit mode
+		// allows before the first render.
 		clampCrop();
 
 		const listeners = new Set();
@@ -729,17 +732,33 @@ window.__ModuleLoader__.load({
 		// never receive pointer events. Adjust mode moves the LIVE layer node into a
 		// topmost transparent overlay — the user edits the real thing, WYSIWYG.
 		//
-		// Crop geometry invariants: the media box covers the viewport exactly at
-		// zoom 1; zooming creates headroom, panning spends it. Zoom floors at 1
-		// and pan is clamped to ±(zoom-1)/2·100 %, so a gap-free fullscreen image
-		// is guaranteed at every setting.
+		// Crop geometry is chosen by the fit mode. The four object-fit modes keep a
+		// GAP-FREE invariant: the media box covers the viewport exactly at zoom 1,
+		// zoom floors at 1, and pan is clamped to ±(zoom−1)/2·100 % — the image
+		// always fills the screen. The "free" mode drops that invariant on purpose:
+		// the media sits at natural size on a black canvas, zoom runs 0.1–4×, and
+		// pan is only clamped to keep a sliver (≥10 % of the box) on screen so the
+		// wallpaper can never be dragged entirely out of sight.
 		function clampCrop() {
-		  selection.zoom = Math.round(Math.min(4, Math.max(1, selection.zoom)) * 100) / 100;
+		  selection.zoom = Math.round(Math.min(4, Math.max(isFreeFit() ? 0.1 : 1, selection.zoom)) * 100) / 100;
+		  if (isFreeFit()) {
+		    // Content spans ±zoom·50 % of the box around its centre; the pan offset
+		    // shifts it by its own % of the box. |offset| ≤ (zoom+1)·50 − 10 keeps
+		    // at least 10 % of the media edge-to-edge visible in both axes.
+		    const reach = (selection.zoom + 1) * 50 - 10;
+		    selection.offsetX = Math.min(reach, Math.max(-reach, selection.offsetX));
+		    selection.offsetY = Math.min(reach, Math.max(-reach, selection.offsetY));
+		    return;
+		  }
 		  const pan = (selection.zoom - 1) * 50;
 		  selection.offsetX = Math.min(pan, Math.max(-pan, selection.offsetX));
 		  selection.offsetY = Math.min(pan, Math.max(-pan, selection.offsetY));
 		}
 
+		function isFreeFit() {
+		  return selection.fit === "free";
+		}
+
 		let adjustOverlay = null;
 		let adjustCleanup = null;
 
@@ -797,7 +816,7 @@ window.__ModuleLoader__.load({
 		    const h = overlay.clientHeight || 1;
 		    selection.offsetX += ((e.clientX - drag.x) / w) * 100;
 		    selection.offsetY += ((e.clientY - drag.y) / h) * 100;
-		    clampCrop(); // gap-free guarantee: pan never outruns the zoom headroom
+		    clampCrop(); // mode envelope: gap-free pan headroom, or free keep-visible
 		    drag = { x: e.clientX, y: e.clientY };
 		    applyEffects();
 		  };
@@ -815,10 +834,10 @@ window.__ModuleLoader__.load({
 		  };
 		  const onWheel = (e) => {
 		    if (typeof e.preventDefault === "function") e.preventDefault();
-		    // Crop semantics: zoom IN only (1–4×). Zooming below cover would float a
-		    // shrunken box in empty space — that is not a crop. Tightening zoom also
-		    // re-clamps the pan into the new headroom, so zooming back to 1 pulls
-		    // the framing home instead of leaving edge gaps.
+		    // clampCrop enforces the mode's zoom floor: the gap-free modes never
+		    // zoom below 1 (a shrunken box floating in empty space is not a crop)
+		    // and tightening zoom re-clamps the pan so zooming back to 1 pulls the
+		    // framing home; free mode shrinks down to 0.1× on its black canvas.
 		    selection.zoom *= Math.exp(-(e.deltaY || 0) * 0.0012);
 		    clampCrop();
 		    applyEffects();
@@ -1044,8 +1063,11 @@ window.__ModuleLoader__.load({
 		    selection.wallpaperBlur > 0 ? (0.02 + selection.wallpaperBlur * 0.0004).toFixed(4) : "0");
 		  // Canvas fit: object-fit base mode plus the user's manual crop — pan
 		  // offsets (percent of the media box) and zoom, applied as a transform so
-		  // no remount is ever needed while dragging.
-		  s.setProperty("--webg-fit", selection.fit);
+		  // no remount is ever needed while dragging. "free" draws at natural size
+		  // (object-fit: none) and paints the layer black, so exposed edges read as
+		  // a canvas instead of whatever sits behind the app frame.
+		  s.setProperty("--webg-fit", selection.fit === "free" ? "none" : selection.fit);
+		  s.setProperty("--webg-layer-bg", selection.fit === "free" ? "#000" : "transparent");
 		  s.setProperty("--webg-zoom", String(selection.zoom));
 		  s.setProperty("--webg-offset-x", selection.offsetX + "%");
 		  s.setProperty("--webg-offset-y", selection.offsetY + "%");
@@ -1071,6 +1093,7 @@ window.__ModuleLoader__.load({
 		  s.removeProperty("--webg-noise-display");
 		  s.removeProperty("--webg-noise-opacity");
 		  s.removeProperty("--webg-fit");
+		  s.removeProperty("--webg-layer-bg");
 		  s.removeProperty("--webg-zoom");
 		  s.removeProperty("--webg-offset-x");
 		  s.removeProperty("--webg-offset-y");
@@ -1268,6 +1291,10 @@ window.__ModuleLoader__.load({
 
 		function onFit(e) {
 		  selection.fit = FIT_MODES.indexOf(e.target.value) >= 0 ? e.target.value : "cover";
+		  // Re-seat the crop into the new mode's envelope: leaving free for a
+		  // gap-free mode pulls zoom back up to 1 and reins the pan in; the other
+		  // direction only ever relaxes bounds, so the framing carries over.
+		  clampCrop();
 		  persistSelection();
 		  applyEffects();
 		  emit();
@@ -1496,19 +1523,20 @@ window.__ModuleLoader__.load({
 
 		function EffectsPanel(t, sel) {
 		  return React.createElement(React.Fragment, null,
-		    // object-fit only means something for video/still wallpapers — an
-		    // iframe ignores it and always fills its layer — so the base-mode
-		    // select is hidden for web. The manual crop (drag / wheel in the
-		    // adjust overlay) is a plain CSS transform and applies to EVERY kind,
-		    // so 调整画面 / 重置裁剪 stay available even for iframes.
+		    // The fit select covers all wallpaper types: for video/stills it picks
+		    // the object-fit base mode, and "free" additionally unlocks shrink +
+		    // off-edge dragging for every kind — an iframe ignores object-fit, but
+		    // the zoom/pan transform applies to it the same way. The manual crop
+		    // (drag / wheel in the adjust overlay) is a plain CSS transform and
+		    // applies to EVERY kind, so 调整画面 / 重置裁剪 are always available.
 		    React.createElement("div", { className: "webg-row webg-fit-row" },
-		      sel.type !== "web" && React.createElement("span", { className: "webg-hint webg-label" }, t.fit),
-		      sel.type !== "web" && React.createElement("select", {
+		      React.createElement("span", { className: "webg-hint webg-label" }, t.fit),
+		      React.createElement("select", {
 		        className: "webg-select webg-fit-select",
 		        value: sel.fit,
 		        onChange: onFit,
 		      },
-		      ...[t.fitCover, t.fitContain, t.fitFill, t.fitNone].map((label, i) =>
+		      ...[t.fitCover, t.fitContain, t.fitFill, t.fitNone, t.fitFree].map((label, i) =>
 		        React.createElement("option", { key: FIT_MODES[i], value: FIT_MODES[i] }, label),
 		      )),
 		      React.createElement("button", {
@@ -1623,10 +1651,13 @@ window.__ModuleLoader__.load({
 		// Everything reads DSH design tokens (--dsw-*) so the UI blends into the
 		// shell and follows light/dark theme switches automatically.
 		const CSS = `
-		  /* Wallpaper layers: fixed, sunk below the app frame, crossfading. */
+		  /* Wallpaper layers: fixed, sunk below the app frame, crossfading. The
+		     background paints black only in the "free" fit mode, where the media
+		     can be dragged off the edges and the exposed area reads as a canvas. */
 		  .webg-layer {
 		    position: fixed; inset: 0; z-index: -2; overflow: hidden;
 		    pointer-events: none; opacity: 1;
+		    background: var(--webg-layer-bg, transparent);
 		    transition: opacity ${CROSSFADE_MS}ms ease;
 		  }
 		  .webg-layer--enter { opacity: 0; }

package/package.json

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