wallpaper-engine-dsh 1.0.6 → 1.0.7

package/README.md

@@ -8,7 +8,7 @@ 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, 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.
 
@@ -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,7 +8,7 @@
 
 **只列出能真实播放的壁纸。** 网格中列出浏览器可以真实渲染的全部类型——视频与网页壁纸。场景/应用壁纸是 Wallpaper Engine 私有的 `.pkg` 场景包,浏览器无法执行,因此直接过滤,不以降级的静态图代替。列出的每张壁纸都真实播放,并按 视频/网页 标注类型;搜索框可按标题或创意工坊 ID 筛选较大的壁纸库。
 
-**任何壁纸上文字都可读。** 遮罩颜色始终与文字颜色相反:深色主题用黑色遮罩,浅色主题用白色遮罩,因此过亮或过暗的壁纸都不会盖住文字。在此基础上,「智能可视」每隔几秒采样一次壁纸亮度,亮度过高或过低时自动加强遮罩。下拉菜单、弹窗等浮层显示在 DSH 原生的不透明表面上,不受影响。
+**任何壁纸上文字都可读。** 遮罩颜色始终与文字颜色相反:深色主题用黑色遮罩,浅色主题用白色遮罩,因此过亮或过暗的壁纸都不会盖住文字。在此基础上,「智能可视」每隔几秒采样一次壁纸亮度,亮度过高或过低时自动加强遮罩(网页壁纸的像素在沙箱中读不到,改用其预览图作为采样依据)。下拉菜单、弹窗等浮层显示在 DSH 原生的不透明表面上,不受影响。
 
 **手动取景。** 先选基础排布(填充、适应、拉伸、原始、自由),再手动调整画面:点「调整画面」将壁纸全屏展开,滚轮缩放,拖动平移。前四种排布下裁剪范围经过限制,画面始终铺满屏幕,不露出边缘;「自由」把壁纸按原始大小放在黑色画布上,可拖动到任意位置,缩放范围 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

@@ -622,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.
@@ -1040,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
@@ -1065,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() {
@@ -1759,12 +1811,20 @@ 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;
@@ -2164,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.6",
+  "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",