wallpaper-engine-dsh 1.0.5 → 1.0.7

package/README.md

@@ -8,9 +8,9 @@ A DSH bundle that turns your local **Wallpaper Engine** library into the live ba
 
 **The library, rendered live.** The grid lists every wallpaper the browser can genuinely render — video and web wallpapers. Scene and application wallpapers are Wallpaper Engine's private `.pkg` scene packages; since no browser can execute them, they are filtered out rather than offered as degraded stills. Everything listed plays for real, badged Video or Web, and a search box narrows large libraries by title or workshop id instantly.
 
-**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.
+**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 (web wallpapers' pixels are unreadable inside the sandbox, so their preview still stands in as the sample); 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, 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.
+**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.
 
@@ -58,7 +58,7 @@ The bundle has two halves:
   - `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.
 
-Media serving is defensive by design: tokens are unguessable 72-bit values, stable across inventory rebuilds (an in-flight stream is never killed by a background refresh) and re-minted only on an explicit refresh; sub-asset paths are contained lexically and re-verified against the real filesystem so symlinks cannot escape their wallpaper directory; HTML and SVG responses carry a `sandbox` CSP so they can never execute against the DSH origin; the wildcard CORS on media only lets a caller who already knows a token read bytes it could already request — the token stays the capability, and the server is loopback-only; and responses that would come up short destroy themselves rather than truncate silently. The host answers from a 30-second inventory cache, resolves discovery asynchronously off the request path, and caches it for ten minutes. The bundle registers no model tools and adds no prompt text.
+Media serving is defensive by design: tokens are unguessable 72-bit values, stable across inventory rebuilds (an in-flight stream is never killed by a background refresh) and re-minted only on an explicit refresh; sub-asset paths are contained lexically and re-verified against the real filesystem so symlinks cannot escape their wallpaper directory; HTML and SVG responses carry a `sandbox` CSP so they can never execute against the DSH origin; the wallpaper iframe additionally pins a neutral `color-scheme`, so the shell's dark-theme scheme never leaks into — and breaks — third-party wallpaper apps; the wildcard CORS on media only lets a caller who already knows a token read bytes it could already request — the token stays the capability, and the server is loopback-only; and responses that would come up short destroy themselves rather than truncate silently. The host answers from a 30-second inventory cache, resolves discovery asynchronously off the request path, and caches it for ten minutes. The bundle registers no model tools and adds no prompt text.
 
 ## Limitations
 

package/README.zh.md

@@ -8,9 +8,9 @@
 
 **只列出能真实播放的壁纸。** 网格中列出浏览器可以真实渲染的全部类型——视频与网页壁纸。场景/应用壁纸是 Wallpaper Engine 私有的 `.pkg` 场景包,浏览器无法执行,因此直接过滤,不以降级的静态图代替。列出的每张壁纸都真实播放,并按 视频/网页 标注类型;搜索框可按标题或创意工坊 ID 筛选较大的壁纸库。
 
-**任何壁纸上文字都可读。** 遮罩颜色始终与文字颜色相反:深色主题用黑色遮罩,浅色主题用白色遮罩,因此过亮或过暗的壁纸都不会盖住文字。在此基础上,「智能可视」每隔几秒采样一次壁纸亮度,亮度过高或过低时自动加强遮罩。下拉菜单、弹窗等浮层显示在 DSH 原生的不透明表面上,不受影响。
+**任何壁纸上文字都可读。** 遮罩颜色始终与文字颜色相反:深色主题用黑色遮罩,浅色主题用白色遮罩,因此过亮或过暗的壁纸都不会盖住文字。在此基础上,「智能可视」每隔几秒采样一次壁纸亮度,亮度过高或过低时自动加强遮罩(网页壁纸的像素在沙箱中读不到,改用其预览图作为采样依据)。下拉菜单、弹窗等浮层显示在 DSH 原生的不透明表面上,不受影响。
 
-**手动取景。** 先选基础排布(填充、适应、拉伸、原始、自由),再手动调整画面:点「调整画面」将壁纸全屏展开,滚轮缩放,拖动平移。前四种排布下裁剪范围经过限制,画面始终铺满屏幕,不露出边缘;「自由」把壁纸按原始大小放在黑色画布上,可拖动到任意位置,缩放范围 0.1–4×,并始终保留一小块在屏幕内,不会拖丢。按 Esc 或点「完成」退出,取景设置会保存,「重置裁剪」可一键恢复默认。网页壁纸使用相同的排布下拉与缩放/平移取景(变换直接作用于 iframe)。
+**手动取景。** 先选基础排布(填充、适应、拉伸、原始、自由),再手动调整画面:点「调整画面」将壁纸全屏展开,滚轮缩放,拖动平移。前四种排布下裁剪范围经过限制,画面始终铺满屏幕,不露出边缘;「自由」把壁纸按原始大小放在黑色画布上,可拖动到任意位置,缩放范围 0.1–4×,并可旋转任意角度(±90° 按钮或 Alt+拖动),同时始终保留一小块在屏幕内,不会拖丢。「镜像」水平翻转壁纸,所有排布下都可用——翻转不会破坏铺满。按 Esc 或点「完成」退出,取景设置会保存,「重置裁剪」可一键恢复默认。网页壁纸使用相同的排布下拉与缩放/平移/旋转取景(变换直接作用于 iframe)。
 
 **四个实时滑杆。** 壁纸模糊、暗化、边框、玻璃,每一步调节立即生效并保存。模糊在原位渲染:任意模糊度下,画面的比例、排布与取景完全一致;屏幕边缘一个模糊半径内的画面向遮罩过渡,被界面边饰覆盖,通常不可见。模糊时叠加轻微噪声,消除渐变色带;模糊为零时媒体完全绕过滤镜管线,像素保持不变。
 
@@ -58,7 +58,7 @@ bundle 分为两半:
   - `GET /we-background/preview/<token>`
 - **浏览器插件** 把选中的壁纸渲染在应用框架之下的固定层,提供设置界面,所有视觉效果都读取 DSH 设计令牌,主题切换时自动适配。
 
-媒体服务在多个层面做了防护:令牌是无法猜测的 72 位随机值,清单重建时保持不变(后台刷新不会中断正在播放的流),只在显式刷新时重新生成;子资源路径先做词法包含检查,再对照真实文件系统复核,符号链接无法指向壁纸目录之外;HTML 与 SVG 响应带 `sandbox` CSP,不能以 DSH 源的身份执行;媒体响应的 CORS 通配只允许持有令牌的一方读取其本来就能请求的文件,访问权限仍由令牌决定,且整个服务只监听本机回环地址;长度不足的响应会直接中断,而不是悄悄截断。清单由宿主缓存 30 秒;安装位置的发现过程在请求路径之外异步执行,并缓存 10 分钟。本插件不注册模型工具,不占用 prompt。
+媒体服务在多个层面做了防护:令牌是无法猜测的 72 位随机值,清单重建时保持不变(后台刷新不会中断正在播放的流),只在显式刷新时重新生成;子资源路径先做词法包含检查,再对照真实文件系统复核,符号链接无法指向壁纸目录之外;HTML 与 SVG 响应带 `sandbox` CSP,不能以 DSH 源的身份执行;壁纸 iframe 固定使用中性 `color-scheme`,外壳的深色主题不会泄漏进(并破坏)第三方壁纸应用;媒体响应的 CORS 通配只允许持有令牌的一方读取其本来就能请求的文件,访问权限仍由令牌决定,且整个服务只监听本机回环地址;长度不足的响应会直接中断,而不是悄悄截断。清单由宿主缓存 30 秒;安装位置的发现过程在请求路径之外异步执行,并缓存 10 分钟。本插件不注册模型工具,不占用 prompt。
 
 ## 限制
 

package/lib/client.js

@@ -95,6 +95,12 @@ window.__ModuleLoader__.load({
 		    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,
@@ -173,6 +179,12 @@ window.__ModuleLoader__.load({
 		    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,
@@ -226,6 +238,8 @@ 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", "free"];
@@ -281,6 +295,8 @@ window.__ModuleLoader__.load({
 		      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 };
@@ -339,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 */ }
 		}
@@ -604,6 +622,10 @@ window.__ModuleLoader__.load({
 		  if (isPlayable(w) && !demotedToPreview.has(selection.id)) {
 		    selection.url = w.media;
 		    selection.type = w.type; // "video" | "web"
+		    // Brightness evidence belongs to the showing wallpaper: leaving a web
+		    // wallpaper must drop its preview-based estimate instead of letting it
+		    // mis-veil the next media until its own first frame arrives.
+		    if (selection.type !== "web") sampledLuminance = null;
 		  } else if (isPlayable(w) && w.preview) {
 		    // Playable wallpaper demoted after repeated media failures (an
 		    // undecodable container) — its preview still is the graceful fallback.
@@ -734,18 +756,32 @@ window.__ModuleLoader__.load({
 		//
 		// 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.
+		// 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() {
+		  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. |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;
+		    // 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;
@@ -786,12 +822,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);
@@ -801,14 +856,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.
@@ -820,18 +895,16 @@ window.__ModuleLoader__.load({
 		    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();
 		    // clampCrop enforces the mode's zoom floor: the gap-free modes never
@@ -870,6 +943,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();
@@ -970,23 +1044,31 @@ window.__ModuleLoader__.load({
 		    }, LEAVE_MS);
 		  }
 
-		  // Scrim: present while a wallpaper is active. On clear it outlives the
-		  // layer until the fade-out finishes, so the veil fades WITH the wallpaper.
-		  if (selection.url) {
-		    const scrim = document.getElementById(SCRIM_ID);
-		    if (!scrim) {
-		      const s = document.createElement("div");
-		      s.id = SCRIM_ID;
-		      s.className = "webg-scrim";
-		      document.body.appendChild(s);
+		    // Scrim: present while a wallpaper is active. On clear it outlives the
+		    // layer until the fade-out finishes, so the veil fades WITH the wallpaper.
+		    if (selection.url) {
+		      const scrim = document.getElementById(SCRIM_ID);
+		      if (!scrim) {
+		        const s = document.createElement("div");
+		        s.id = SCRIM_ID;
+		        s.className = "webg-scrim";
+		        document.body.appendChild(s);
+		      }
+		      document.body.setAttribute(ACTIVE_ATTR, "on");
+		      // Keep the smart veil's preview probe pointed at the showing web
+		      // wallpaper (mount and token re-issue alike).
+		      if (selection.type === "web") {
+		        const w = selection.inventory.wallpapers.find((x) => x.id === selection.id);
+		        if (w && w.preview) probePreviewLuminance(w.preview);
+		      }
 		    }
-		    document.body.setAttribute(ACTIVE_ATTR, "on");
-		  }
 		}
 
 		// ── 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).
+		// sample). Web wallpapers render in an opaque-origin iframe whose pixels are
+		// unreadable — for those, the inventory's PREVIEW still stands in as a
+		// brightness proxy (see probePreviewLuminance).
 		let sampledLuminance = null;
 		let sampleCanvas = null;
 		// Snapshot of every input applyEffects reads, from its last full write. The
@@ -995,29 +1077,69 @@ window.__ModuleLoader__.load({
 		// nothing. clearEffects() resets it so the next apply always writes.
 		let lastEffectKey = 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; }
+		/** Average Rec.601 luminance (0..1) of a drawable media frame, or null. */
+		function luminanceOf(media) {
 		  try {
 		    if (!sampleCanvas) {
 		      const c = document.createElement("canvas");
-		      if (typeof c.getContext !== "function") return; // no canvas → no sampling
+		      if (typeof c.getContext !== "function") return null; // 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;
-		    if (!d || d.length < 4) return; // unreadable frame → keep previous sample
+		    if (!d || d.length < 4) return null; // 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];
 		    }
-		    sampledLuminance = sum / (d.length / 4) / 255;
-		  } catch { /* frame not ready / unreadable → keep the previous sample */ }
+		    return sum / (d.length / 4) / 255;
+		  } catch { return null; /* frame not ready / unreadable → keep previous */ }
+		}
+
+		// Hidden preview probe: whenever a web wallpaper is showing, its preview
+		// still (same-origin through our route) is decoded here so the smart veil
+		// can read the wallpaper's rough brightness even though the sandboxed
+		// iframe's own pixels are forever unreadable.
+		const PREVIEW_PROBE_ID = "wallpaper-engine-dsh-preview-probe";
+		let previewProbe = null;
+		function probePreviewLuminance(url) {
+		  if (!url) return;
+		  if (!previewProbe) {
+		    previewProbe = document.createElement("img");
+		    previewProbe.id = PREVIEW_PROBE_ID;
+		    previewProbe.alt = "";
+		    previewProbe.setAttribute("decoding", "async");
+		    // Offscreen, invisible, 1px: it exists to be decoded and drawn, nothing
+		    // else. Attached to <body> so tooling (and our verify harness) can see it.
+		    previewProbe.setAttribute("style",
+		      "position:fixed;left:-10px;top:-10px;width:1px;height:1px;opacity:0;pointer-events:none");
+		    previewProbe.addEventListener("load", () => {
+		      // A GIF preview draws its first frame — plenty for a brightness proxy.
+		      const lum = luminanceOf(previewProbe);
+		      if (lum !== null && selection.type === "web") {
+		        sampledLuminance = lum;
+		        applyEffects();
+		      }
+		    });
+		    document.body.appendChild(previewProbe);
+		  }
+		  if (previewProbe.getAttribute("src") !== url) previewProbe.src = url;
+		}
+
+		function sampleWallpaperLuminance() {
+		  if (typeof document === "undefined") return;
+		  const layer = document.getElementById(LAYER_ID);
+		  const media = layer && (layer.querySelector("video") || layer.querySelector("img"));
+		  if (!media) {
+		    // Nothing live to sample. A web wallpaper keeps its preview-based
+		    // estimate; any other kind has no brightness evidence at all.
+		    if (selection.type !== "web") sampledLuminance = null;
+		    return;
+		  }
+		  const lum = luminanceOf(media);
+		  if (lum !== null) sampledLuminance = lum;
 		}
 
 		function applyEffects() {
@@ -1028,7 +1150,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;
@@ -1071,6 +1193,8 @@ window.__ModuleLoader__.load({
 		  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.
@@ -1097,6 +1221,8 @@ window.__ModuleLoader__.load({
 		  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 = "";
 		}
@@ -1292,14 +1418,23 @@ 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.
+		  // 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();
+		}
+
 		// ── Picker sections (presentational; every input arrives as an argument) ────
 		// WallpaperPicker composes these in a fixed order. Each one owns exactly one
 		// visual row/block of the settings panel and produces the same DOM the old
@@ -1539,6 +1674,13 @@ window.__ModuleLoader__.load({
 		      ...[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,
@@ -1669,20 +1811,32 @@ window.__ModuleLoader__.load({
 		     Gaussian's natural edge fade (≤ one blur radius, under the veil and the
 		     UI chrome) is accepted. A slight saturate keeps blurred colours from
 		     washing out. */
+		  /* color-scheme: normal stops the DSH theme from leaking INTO the sandboxed
+		     web-wallpaper iframe. The shell sets color-scheme: dark on <html> in the
+		     dark theme; that value propagates to embedded documents, and at least one
+		     official wallpaper (CORSAIR Collection, an Angular app) never paints
+		     under an inherited dark scheme — a solid white page instead. The value
+		     "normal" restores the neutral default; a wallpaper that opts into a
+		     scheme via its own styles still wins. */
 		  .webg-layer .webg-media {
 		    position: absolute;
 		    inset: 0;
 		    width: 100%;
 		    height: 100%;
 		    max-width: none; max-height: none;
+		    color-scheme: normal;
 		    object-fit: var(--webg-fit, cover);
 		    object-position: center;
 		    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;
 		  }
 
@@ -1803,17 +1957,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;
@@ -1873,7 +2042,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;
@@ -1971,7 +2140,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;
 		  }
 		`;
@@ -2055,6 +2224,7 @@ window.__ModuleLoader__.load({
 		        if (samplerId !== null) window.clearInterval(samplerId);
 		        if (observer) observer.disconnect();
 		        sampledLuminance = null;
+		        if (previewProbe) { previewProbe.remove(); previewProbe = null; }
 		        clearRotationTimer();
 		        // Cancel pending crossfade/clear timers so they never fire on
 		        // torn-down nodes after dispose.

package/package.json

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