wallpaper-engine-dsh 1.0.4 → 1.0.6

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, zoomed from 0.1× to 4×, and rotated to any angle (±90° buttons or Alt+drag), with just enough kept on screen that it can never be dragged out of sight. **Mirror** flips the wallpaper horizontally and works in every layout — a flip never exposes an edge. 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/rotate 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×,并可旋转任意角度(±90° 按钮或 Alt+拖动),同时始终保留一小块在屏幕内,不会拖丢。「镜像」水平翻转壁纸,所有排布下都可用——翻转不会破坏铺满。按 Esc 或点「完成」退出,取景设置会保存,「重置裁剪」可一键恢复默认。网页壁纸使用相同的排布下拉与缩放/平移/旋转取景(变换直接作用于 iframe)。
 
 **四个实时滑杆。** 壁纸模糊、暗化、边框、玻璃,每一步调节立即生效并保存。模糊在原位渲染:任意模糊度下,画面的比例、排布与取景完全一致;屏幕边缘一个模糊半径内的画面向遮罩过渡,被界面边饰覆盖,通常不可见。模糊时叠加轻微噪声,消除渐变色带;模糊为零时媒体完全绕过滤镜管线,像素保持不变。
 

package/lib/client.js

@@ -91,9 +91,16 @@ window.__ModuleLoader__.load({
 		    fitContain: "适应",
 		    fitFill: "拉伸",
 		    fitNone: "原始",
+		    fitFree: "自由",
 		    adjust: "调整画面",
 		    adjustDone: "完成",
 		    adjustHint: "拖动平移 · 滚轮缩放 · Esc 或点「完成」退出",
+		    adjustHintFree: "拖动平移 · 滚轮缩放 · Alt+拖动旋转 · Esc 或点「完成」退出",
+		    mirror: "镜像",
+		    rotateCcw: "⟲",
+		    rotateCw: "⟳",
+		    rotateCcwTitle: "逆时针旋转 90°",
+		    rotateCwTitle: "顺时针旋转 90°",
 		    resetCrop: "重置裁剪",
 		    statusGroup: (name, total, usable, interval, order) =>
 		      "列表「" + name + "」:" + total + " 项 · " + usable + " 可用 · 每 " + interval + " 分钟 · " + order,
@@ -168,9 +175,16 @@ 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",
+		    adjustHintFree: "Drag to pan · wheel to zoom · Alt+drag to rotate · Esc or Done to exit",
+		    mirror: "Mirror",
+		    rotateCcw: "⟲",
+		    rotateCw: "⟳",
+		    rotateCcwTitle: "Rotate 90° counterclockwise",
+		    rotateCwTitle: "Rotate 90° clockwise",
 		    resetCrop: "Reset crop",
 		    statusGroup: (name, total, usable, interval, order) =>
 		      "List \"" + name + "\": " + total + " items · " + usable + " usable · every " + interval + " min · " + order,
@@ -224,9 +238,11 @@ window.__ModuleLoader__.load({
 		  zoom: 1,
 		  offsetX: 0,
 		  offsetY: 0,
+		  rotation: 0, // free-fit only; degrees, positive = clockwise
+		  mirrored: false, // horizontal flip, available in every fit mode
 		};
 
-		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 +289,14 @@ 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),
+		      rotation: clampNum(o.rotation, -1080, 1080, DEFAULTS.rotation),
+		      mirrored: o.mirrored === true,
 		    };
 		  } catch {
 		    return { id: "", ...DEFAULTS };
@@ -302,8 +321,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();
@@ -336,6 +355,8 @@ window.__ModuleLoader__.load({
 		      zoom: selection.zoom,
 		      offsetX: selection.offsetX,
 		      offsetY: selection.offsetY,
+		      rotation: selection.rotation,
+		      mirrored: selection.mirrored,
 		    }));
 		  } catch { /* storage full / blocked → session-only state, not fatal */ }
 		}
@@ -729,17 +750,47 @@ 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, pan is clamped to ±(zoom−1)/2·100 %, and rotation is
+		// forced to 0 — a rotated rectangle cannot cover the screen, so turning
+		// belongs to free mode only. Mirroring is allowed everywhere: a flip is
+		// symmetric and never breaks coverage. The "free" mode drops the gap-free
+		// invariant on purpose: the media sits at natural size on a black canvas,
+		// zoom runs 0.1–4×, rotation is arbitrary, 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;
+		  if (!isFreeFit()) selection.rotation = 0;
+		  else {
+		    // Keep the stored angle canonical (−180, 180]: Alt+drag can accumulate
+		    // several full turns, and persisting raw degrees would come back from
+		    // storage truncated at the ±1080 read clamp — a DIFFERENT visual angle.
+		    // Modulo keeps every equivalent representation identical on disk.
+		    selection.rotation = ((selection.rotation + 180) % 360 + 360) % 360 - 180;
+		  }
+		  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. Rotation expands the projected
+		    // extent by k = |cos θ| + |sin θ| (up to √2 at 45°). |offset| ≤
+		    // (zoom·k+1)·50 − 10 keeps ≥10 % of the media visible in both axes.
+		    const rad = selection.rotation * Math.PI / 180;
+		    const k = Math.abs(Math.cos(rad)) + Math.abs(Math.sin(rad));
+		    const reach = (selection.zoom * k + 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;
 
@@ -767,12 +818,31 @@ window.__ModuleLoader__.load({
 		  bar.className = "webg-adjust-bar";
 		  const hint = document.createElement("span");
 		  hint.className = "webg-adjust-hint";
-		  hint.textContent = S().adjustHint;
+		  hint.textContent = isFreeFit() ? S().adjustHintFree : S().adjustHint;
 		  const done = document.createElement("button");
 		  done.type = "button";
 		  done.className = "webg-btn webg-btn--primary";
 		  done.textContent = S().adjustDone;
 		  bar.appendChild(hint);
+		  // Free fit only: a rotated rectangle cannot cover the screen, so turning
+		  // exists solely where exposed edges are allowed. ±90° buttons cover the
+		  // common cases; arbitrary angles come from Alt+drag below.
+		  if (isFreeFit()) {
+		    for (const dir of [-90, 90]) {
+		      const rot = document.createElement("button");
+		      rot.type = "button";
+		      rot.className = "webg-btn";
+		      rot.textContent = dir < 0 ? S().rotateCcw : S().rotateCw;
+		      rot.title = dir < 0 ? S().rotateCcwTitle : S().rotateCwTitle;
+		      rot.addEventListener("click", () => {
+		        selection.rotation += dir;
+		        clampCrop();
+		        applyEffects();
+		        persistSelection();
+		      });
+		      bar.appendChild(rot);
+		    }
+		  }
 		  bar.appendChild(done);
 		  overlay.appendChild(bar);
 		  document.body.appendChild(overlay);
@@ -782,14 +852,34 @@ window.__ModuleLoader__.load({
 		  // 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;
+		  // Alt+drag (free fit): swing the media around the overlay's centre —
+		  // the angle delta between pointer positions becomes the rotation delta.
+		  let rot = null; // { a0: starting pointer angle, base: starting rotation }
+		  const centerAngle = (e) => {
+		    const cx = (overlay.clientWidth || 1) / 2;
+		    const cy = (overlay.clientHeight || 1) / 2;
+		    return Math.atan2(e.clientY - cy, e.clientX - cx);
+		  };
 		  const onPointerDown = (e) => {
 		    if (e.target === done || bar.contains(e.target)) return;
-		    drag = { x: e.clientX, y: e.clientY };
+		    if (e.altKey && isFreeFit()) {
+		      rot = { a0: centerAngle(e), base: selection.rotation };
+		    } else {
+		      drag = { x: e.clientX, y: e.clientY };
+		    }
+		    // Capture for EITHER gesture: pointer moves must keep arriving even
+		    // when the cursor leaves the window mid-swing.
 		    if (overlay.setPointerCapture && e.pointerId !== undefined) {
 		      try { overlay.setPointerCapture(e.pointerId); } catch {}
 		    }
 		  };
 		  const onPointerMove = (e) => {
+		    if (rot) {
+		      selection.rotation = rot.base + (centerAngle(e) - rot.a0) * 180 / Math.PI;
+		      clampCrop();
+		      applyEffects();
+		      return;
+		    }
 		    if (!drag) return;
 		    // translate % refers to the media box, which is the viewport exactly —
 		    // divide the pixel delta by it so the content tracks the cursor 1:1.
@@ -797,28 +887,26 @@ 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();
 		  };
-		  const onPointerUp = () => {
+		  const endPointer = () => {
+		    if (rot) { rot = null; persistSelection(); return; }
 		    if (!drag) return;
 		    drag = null;
 		    persistSelection();
 		  };
+		  const onPointerUp = endPointer;
 		  // 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 onPointerCancel = endPointer;
 		  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();
@@ -851,6 +939,7 @@ window.__ModuleLoader__.load({
 		  selection.zoom = 1;
 		  selection.offsetX = 0;
 		  selection.offsetY = 0;
+		  selection.rotation = 0; // framing geometry home; mirroring keeps its own toggle
 		  persistSelection();
 		  applyEffects();
 		  emit();
@@ -1009,7 +1098,7 @@ window.__ModuleLoader__.load({
 		  const key = [
 		    dark, selection.scrim, selection.border, selection.blur, selection.wallpaperBlur,
 		    selection.autoScrim, sampledLuminance, selection.fit, selection.zoom,
-		    selection.offsetX, selection.offsetY,
+		    selection.offsetX, selection.offsetY, selection.rotation, selection.mirrored,
 		  ].join("\u0000");
 		  if (key === lastEffectKey) return; // nothing it reads changed → no writes, no reflow
 		  lastEffectKey = key;
@@ -1044,11 +1133,16 @@ 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 + "%");
+		  s.setProperty("--webg-rotate", selection.rotation + "deg");
+		  s.setProperty("--webg-mirror", selection.mirrored ? "-1" : "1");
 
 		  // Write the scrim colour directly too, then force a synchronous layout, so
 		  // slider feedback lands on this frame even on stalled compositors.
@@ -1071,9 +1165,12 @@ 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");
+		  s.removeProperty("--webg-rotate");
+		  s.removeProperty("--webg-mirror");
 		  const scrim = document.getElementById(SCRIM_ID);
 		  if (scrim) scrim.style.background = "";
 		}
@@ -1268,6 +1365,19 @@ 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, reins the pan in and zeroes the
+		  // rotation; the other direction only ever relaxes bounds, so the framing
+		  // carries over. Mirroring survives every switch — a flip never breaks
+		  // coverage.
+		  clampCrop();
+		  persistSelection();
+		  applyEffects();
+		  emit();
+		}
+
+		function onToggleMirror() {
+		  selection.mirrored = !selection.mirrored;
 		  persistSelection();
 		  applyEffects();
 		  emit();
@@ -1496,21 +1606,29 @@ 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),
 		      )),
+		      // Mirror is a coverage-preserving flip: valid in EVERY fit mode and
+		      // for every wallpaper kind (the transform applies to iframes too).
+		      React.createElement("button", {
+		        className: "webg-btn" + (sel.mirrored ? " webg-btn--active" : ""),
+		        type: "button",
+		        onClick: onToggleMirror,
+		      }, t.mirror),
 		      React.createElement("button", {
 		        className: "webg-btn", type: "button", onClick: enterAdjust,
 		        disabled: sel.adjusting,
@@ -1623,10 +1741,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; }
@@ -1649,9 +1770,13 @@ window.__ModuleLoader__.load({
 		    display: block;
 		    background: transparent; border: 0;
 		    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));
+		    /* Manual crop: the transform list is ordered pan → rotate → zoom →
+		       mirror. translate comes first so pan offsets stay screen-aligned no
+		       matter the rotation; mirror is innermost so the flip happens in the
+		       media's own axes. */
+		    transform: translate(var(--webg-offset-x, 0%), var(--webg-offset-y, 0%))
+		      rotate(var(--webg-rotate, 0deg)) scale(var(--webg-zoom, 1))
+		      scaleX(var(--webg-mirror, 1));
 		    transform-origin: center center;
 		  }
 
@@ -1772,17 +1897,32 @@ window.__ModuleLoader__.load({
 		    border-color: var(--dsw-alias-border-l1, rgba(128, 128, 128, 0.5));
 		  }
 		  .webg-btn:disabled { opacity: 0.45; cursor: not-allowed; }
-		  /* brand-primary is monochrome (near-black light / near-white dark), so
-		     the label must use its inverse token — never a hardcoded white. */
+		  /* brand-primary is monochrome (near-black light / near-white dark). The
+		     shell's brand-primary-INVERT token aliases the same shade as brand-
+		     primary itself in both themes (no contrast), so anything sitting ON a
+		     brand-primary fill takes its contrast colour from the inverted label
+		     ramp instead — near-white on the dark light-theme fill, dark bluish-800
+		     on the near-white dark-theme fill. */
+		  body {
+		    --webg-on-brand: var(--dsw-alias-label-primary-inverted,
+		      var(--dsw-alias-label-primary-foreground, rgb(249, 250, 251)));
+		  }
 		  .webg-btn--primary {
 		    background: var(--dsw-alias-brand-primary, rgb(15, 17, 21));
 		    border-color: transparent;
-		    color: var(--dsw-alias-brand-primary-invert, rgb(249, 250, 251));
+		    color: var(--webg-on-brand);
 		  }
 		  .webg-btn--primary:hover:not(:disabled) {
 		    background: var(--dsw-alias-brand-primary, rgb(15, 17, 21));
 		    opacity: 0.85;
 		  }
+		  /* Toggle-style button showing an engaged state (e.g. 镜像): brand fill
+		     with the contrasting on-brand label. */
+		  .webg-btn--active {
+		    background: var(--dsw-alias-brand-primary, rgb(15, 17, 21));
+		    border-color: transparent;
+		    color: var(--webg-on-brand);
+		  }
 
 		  .webg-select, .webg-text {
 		    padding: 5px 10px;
@@ -1842,7 +1982,7 @@ window.__ModuleLoader__.load({
 		    -webkit-appearance: none;
 		    width: 14px; height: 14px; border-radius: 50%;
 		    margin-top: -5px; /* centers the 14px thumb on the 4px track */
-		    background: var(--dsw-alias-brand-primary-invert, rgb(249, 250, 251));
+		    background: var(--webg-on-brand);
 		    border: 2.5px solid var(--dsw-alias-brand-primary, rgb(15, 17, 21));
 		    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.28);
 		    transition: transform 120ms ease;
@@ -1940,7 +2080,7 @@ window.__ModuleLoader__.load({
 		    position: absolute; top: 4px; left: 4px; width: 18px; height: 18px;
 		    border-radius: 4px;
 		    background: var(--dsw-alias-brand-primary, rgb(15, 17, 21));
-		    color: var(--dsw-alias-brand-primary-invert, rgb(249, 250, 251));
+		    color: var(--webg-on-brand);
 		    font-size: 12px; line-height: 18px; text-align: center;
 		  }
 		`;

package/package.json

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