wallpaper-engine-dsh 0.1.6 → 0.1.7

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.
+- **Canvas fit** — Cover/Contain/Stretch/Original sizing plus five-way alignment for video and still wallpapers.
 - **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.

package/README.zh.md

@@ -9,7 +9,8 @@
 - **全库浏览** —— 视频与网页壁纸动态渲染；场景与应用壁纸显示预览图作为静态背景。凡是有预览图或可播放文件的壁纸都可选用，按类型标注角标（视频 / 网页 / 静态）。
 - **搜索** —— 按标题或创意工坊 ID 即时筛选网格。
 - **轮播列表** —— 可建任意多个列表，各自拥有壁纸集合、切换间隔（1–120 分钟）和顺序（顺序/随机）。首次运行自动导入第一个可播放的 Wallpaper Engine 播放列表，其余列表可随时导入。
-- **四个实时滑杆** —— 壁纸模糊、暗化、边框对比、玻璃磨砂，即时生效并持久保存。
+- **四个实时滑杆** —— 壁纸模糊、暗化、边框、玻璃，即时生效并持久保存。
+- **任意壁纸都可读** —— 遮罩颜色与文字颜色相对（浅色主题提亮、深色主题压暗）;"智能可视"开关每隔几秒采样一次壁纸亮度，画面过亮或过暗时自动加强遮罩。下拉菜单、弹窗等浮层保持 DSH 原生不透明表面，不受影响。
 - **画布排布** —— 视频与静态壁纸支持填充/适应/拉伸/原始四种排布和五向对齐。
 - **资源监控** —— 帧率读数与低帧率提示，页面隐藏或电量不足时自动暂停（均可开关）。
 - **中英双语** —— 设置界面跟随 DSH 的"语言"偏好自动切换，也可在面板内手动指定。

package/lib/client.js

@@ -79,6 +79,8 @@ window.__ModuleLoader__.load({
 		    glass: "玻璃",
 		    pauseOnHidden: "页面隐藏时暂停",
 		    pauseOnBattery: "低电量时暂停",
+		    autoScrim: "智能可视",
+		    autoScrimTitle: "采样壁纸亮度,过亮或过暗时自动加强遮罩,保证文字可读",
 		    fpsTitle: "页面当前渲染帧率",
 		    lowFpsHint: "帧率偏低,可尝试暂停视频、增大壁纸模糊或换用静态壁纸",
 		    language: "语言",
@@ -157,6 +159,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",
@@ -218,6 +222,7 @@ window.__ModuleLoader__.load({
 		  rotationSeeded: false,
 		  pauseOnHidden: true,
 		  pauseOnBattery: true,
+		  autoScrim: true,
 		  lang: "auto",
 		  fit: "cover",
 		  position: "center",
@@ -268,6 +273,7 @@ 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,
@@ -319,6 +325,7 @@ window.__ModuleLoader__.load({
 		      rotationSeeded: selection.rotationSeeded,
 		      pauseOnHidden: selection.pauseOnHidden,
 		      pauseOnBattery: selection.pauseOnBattery,
+		      autoScrim: selection.autoScrim,
 		      lang: selection.lang,
 		      fit: selection.fit,
 		      position: selection.position,
@@ -660,6 +667,14 @@ window.__ModuleLoader__.load({
 		    media.setAttribute("decoding", "async");
 		    media.className = "webg-media";
 		  }
+		  // First luminance sample as soon as the frame is decodable (video/still
+		  // only — iframe contents are opaque to us). Later samples ride the timer.
+		  if (sel.type === "video" || sel.type === "image") {
+		    media.addEventListener(sel.type === "video" ? "loadeddata" : "load", () => {
+		      sampleWallpaperLuminance();
+		      applyEffects();
+		    });
+		  }
 		  media.addEventListener("error", () => {
 		    const id = sel.id;
 		    const count = (mediaFailures.get(id) || 0) + 1;
@@ -765,9 +780,52 @@ 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.
@@ -785,7 +843,7 @@ window.__ModuleLoader__.load({
 		  // 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;
 		  }
@@ -947,6 +1005,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(); };
@@ -1242,6 +1306,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,
@@ -1612,9 +1682,28 @@ 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();
+		        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/package.json

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