fix(webui): 壁纸被不透明层盖住 —— 玻璃不再层层相乘 + 浅色表面类全部接管

用户报的：「webui 目前在壁纸底上叠了太多不透明层，导致壁纸效果很差，几乎看不出来」，追问后补充：「不只是玻璃，而是很多界面是不透明的」。两句都成立，是两个叠加的原因。 ## ① 玻璃层层相乘每层面板都吃同一个不透明度 a，两层就是 1-(1-a)²。a=0.82 时两层 0.97、三层 0.995 —— 壁纸在数学上被吃掉，而且每层各做一次 16px 模糊，图案被糊成灰块。改法：玻璃只出现一次（外层 0.62 + 18px 模糊；嵌套层只留 0.3 色调且不再模糊；第三层透明）。同时把遮罩 24%→12%、照片自身模糊 8→4px（那张被洗白的锅之一）。 ## ② 14 个浅色表面类根本没被接管（"很多界面是不透明的"就是这条）旧规则只接管 white / gray-50 / slate-100，而源码里在用的是 gray-100(24 处)、blue-50(17)、red-50(13)、blue-100(8)、gray-200(8)、green-50(8)… —— 全是实心的，正好盖住壁纸。清单改为**从源码用法生成**（`scripts/gen-background-takeover.mjs` → 生成的 CSS，构建前自动跑），因为手写清单必然烂；判据保证"源码里出现的浅色表面类必须都被接管"，并明确排除页面底（gray-50/slate-100 必须保持**全透明**，不能被改成半透明）。按钮/徽标（*-600/700、chrome-600/700）**故意保持不透明**：小控件可读性优先（index.css 里原有注释记着实测 4.46:1 的教训）。 ## 判据 - `test/background.test.mjs` 23 条（新增 8 条）：玻璃算式（两层 ≤0.85）、外层 ≤0.70、嵌套规则存在、**判据自检**（旧值 0.82 必须算得出 >0.95）、表面类覆盖、页面底不得进清单、清单非空跑。犯过一次错：第一版把判据追加在 `process.exit()` **之后** ⇒ 根本没执行，从"测试数没变"才发现。 - `test/manual/wallpaper-layers-verify.mjs`（真实渲染，自带无头 Chromium）：用**纯红壁纸读绿通道**测有效不透明度（纯色下 backdrop-filter 不影响读数）。面板 p95：**修复前 82% → 修复后 62%**；反向对照（改回旧值）能分辨 ≥10 个百分点；深色照片面上面板仍是浅底；关掉壁纸的同坐标对照更实。5/5。过程中作废了两个指标：只看绿通道会把深色元素误判成"盖死"；"面积占比"类阈值（Δ≥8/≥40）在 0.97 时仍会蹭过门槛，饱和而无分辨力 —— 同坐标比值才可信。 ## 交付已部署（网关内嵌 WebUI 重建）：线上 CSS 已含 `--bg-glass-inner`、嵌套规则与 14 个接管类。
2026-09-14 08:09:22 +08:00
parent 453f451fbb
commit ababe4ae56
7 changed files with 455 additions and 15 deletions
--- a/client/electron/package.json
+++ b/client/electron/package.json
@ -12,9 +12,9 @@
  "type": "module",
  "main": "electron/main.cjs",
  "scripts": {
-    "dev": "vite",
+    "dev": "npm run gen:bg && vite",
    "dev:electron": "ELECTRON_START_URL=http://localhost:5173 electron electron/main.cjs",
-    "build": "vite build",
+    "build": "npm run gen:bg && vite build",
    "build:win": "vite build && electron-builder --win",
    "build:linux": "vite build && electron-builder --linux",
    "preview": "vite preview",
@ -23,7 +23,8 @@
    "test:narrow": "node test/manual/narrow-verify.mjs",
    "test:wide": "node test/manual/wide-regression.mjs",
    "test:components": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "gen:bg": "node scripts/gen-background-takeover.mjs"
  },
  "dependencies": {
    "lunar-javascript": "1.7.7",
@ -65,14 +66,29 @@
    "win": {
      "icon": "src/icons/icon.ico",
      "target": [
-        { "target": "nsis", "arch": ["x64"] }
+        {
+          "target": "nsis",
+          "arch": [
+            "x64"
+          ]
+        }
      ]
    },
    "linux": {
      "icon": "src/icons",
      "target": [
-        { "target": "AppImage", "arch": ["x64"] },
-        { "target": "deb", "arch": ["x64"] }
+        {
+          "target": "AppImage",
+          "arch": [
+            "x64"
+          ]
+        },
+        {
+          "target": "deb",
+          "arch": [
+            "x64"
+          ]
+        }
      ],
      "category": "Network",
      "synopsis": "以邮件交互为统一范式的多智能体协作平台",
@ -83,4 +99,4 @@
      "allowToChangeInstallationDirectory": true
    }
  }
-}
+}
--- a/client/electron/scripts/gen-background-takeover.mjs
+++ b/client/electron/scripts/gen-background-takeover.mjs
@ -0,0 +1,73 @@
+/**
+ * 生成"背景开启时哪些浅色表面类要变半透明"的 CSS。
+ *
+ * # 为什么要生成而不是手写
+ *
+ * 手写清单必然烂：2026-09-13 用户报「很多界面是不透明的，导致壁纸露不出来」，
+ * 一查代码里在用的浅色表面类有 gray-100(24 处)、blue-50(17)、red-50(13)、
+ * gray-200(8)、green-50(8)… 而当时的接管清单只有 white / gray-50 / slate-100 ——
+ * 漏掉的那些全是实心的，正好盖住壁纸。
+ *
+ * 所以清单从**源码里实际出现的类**推导：出现什么就接管什么。新增一个
+ * `bg-purple-50` 而忘了同步，`test/background.test.mjs` 里那条判据会红。
+ *
+ * 只接管"表面段"（50/100/200）：它们是面板底、提示条、卡片这类大面积浅色。
+ * 600/700 那一段是按钮与徽标（小控件、要读得清），**故意保持不透明** —— 见
+ * index.css 里 chrome-600/700 那段注释（实测可读性从 4.46:1 掉到 AA 以下）。
+ */
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SRC = join(HERE, '..', 'src');
+const OUT = join(SRC, 'background-takeover.generated.css');
+
+/** 表面段：浅色大类 + 50/100/200 三档。 */
+const SURFACE = /^bg-([a-z]+)-(50|100|200)$/;
+
+/**
+ * 页面底：**必须完全透明**（背景开启时），不能进这份"半透明"清单。
+ *
+ * 它们铺满整屏，给它们 0.3 的不透明度等于在壁纸上盖一层白纱；而 index.css 里
+ * 已经把它们设成 transparent —— 谁后加载谁生效，生成物在 index.css 之后引入，
+ * 所以漏了这条排除就会把"完全透明"悄悄改回"半透明"。
+ */
+const PAGE_BASE = new Set(['bg-gray-50', 'bg-slate-100']);
+
+async function walk(dir) {
+  const out = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(p)));
+    else if (/\.(tsx?|jsx?)$/.test(e.name)) out.push(p);
+  }
+  return out;
+}
+
+const found = new Set();
+for (const file of await walk(SRC)) {
+  const text = await readFile(file, 'utf8');
+  for (const m of text.matchAll(/bg-[a-z]+-\d{2,3}/g)) {
+    if (SURFACE.test(m[0]) && !PAGE_BASE.has(m[0])) found.add(m[0]);
+  }
+}
+
+const classes = [...found].sort();
+const body = classes
+  .map(
+    (cls) =>
+      `html[data-bg='on'] .${cls} {\n` +
+      `  background-color: rgb(var(--c-${cls.slice(3)}) / var(--bg-glass-inner));\n` +
+      `  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */\n` +
+      `  -webkit-backdrop-filter: none;\n}`,
+  )
+  .join('\n\n');
+
+await writeFile(
+  OUT,
+  `/* 由 scripts/gen-background-takeover.mjs 生成 —— 不要手改。\n` +
+    ` * 背景开启时把源码里在用的浅色表面类改成半透明（清单来自 src/**/*.tsx 的实际用法）。\n` +
+    ` * 共 ${classes.length} 个类：${classes.join(', ')}\n */\n\n${body}\n`,
+);
+console.log(`  生成 ${classes.length} 个类 → ${OUT}`);
--- a/client/electron/src/background-takeover.generated.css
+++ b/client/electron/src/background-takeover.generated.css
@ -0,0 +1,88 @@
+/* 由 scripts/gen-background-takeover.mjs 生成 —— 不要手改。
+ * 背景开启时把源码里在用的浅色表面类改成半透明（清单来自 src/**/*.tsx 的实际用法）。
+ * 共 14 个类：bg-amber-100, bg-amber-50, bg-blue-100, bg-blue-50, bg-gray-100, bg-gray-200, bg-green-100, bg-green-50, bg-orange-100, bg-orange-200, bg-orange-50, bg-red-100, bg-red-50, bg-yellow-100
+ */
+
+html[data-bg='on'] .bg-amber-100 {
+  background-color: rgb(var(--c-amber-100) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-amber-50 {
+  background-color: rgb(var(--c-amber-50) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-blue-100 {
+  background-color: rgb(var(--c-blue-100) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-blue-50 {
+  background-color: rgb(var(--c-blue-50) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-gray-100 {
+  background-color: rgb(var(--c-gray-100) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-gray-200 {
+  background-color: rgb(var(--c-gray-200) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-green-100 {
+  background-color: rgb(var(--c-green-100) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-green-50 {
+  background-color: rgb(var(--c-green-50) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-orange-100 {
+  background-color: rgb(var(--c-orange-100) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-orange-200 {
+  background-color: rgb(var(--c-orange-200) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-orange-50 {
+  background-color: rgb(var(--c-orange-50) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-red-100 {
+  background-color: rgb(var(--c-red-100) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-red-50 {
+  background-color: rgb(var(--c-red-50) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-yellow-100 {
+  background-color: rgb(var(--c-yellow-100) / var(--bg-glass-inner));
+  backdrop-filter: none;   /* 外层已经模糊过，嵌套层再糊一次会把图案糊成灰块 */
+  -webkit-backdrop-filter: none;
+}
--- a/client/electron/src/index.css
+++ b/client/electron/src/index.css
@ -225,10 +225,24 @@
   * --bg-dim 与 --bg-blur 由 backgroundStore 在运行时写入，这里是初值。
   */
  --bg-scrim: 255 255 255;
-  --bg-dim: 24%;
-  --bg-blur: 8px;
+  --bg-dim: 12%;
+  --bg-blur: 4px;
  /* 玻璃面板的不透明度：背景越花，面板需要越实才读得动。 */
-  --bg-glass: 0.82;
+  --bg-glass: 0.62;
+  /*
+   * 嵌套面板那一层的不透明度。
+   *
+   * ★ 为什么必须有这个变量（2026-09-13 用户报的缺陷）：「壁纸底上叠了太多
+   * 不透明层，导致壁纸效果很差，几乎看不出来」。根因就是**每一层 bg-white
+   * 都用同一个 0.82**，而嵌套是相乘的：0.82 × 0.82 = 0.97，再叠一层就到 0.995
+   * —— 壁纸被彻底盖住，而且每层各做一次模糊，图案被糊成一片灰。
+   *
+   * 原则是「玻璃只该出现一次」：最外层负责遮罩与模糊，里面几层只留一点点
+   * 色调（保住正文对比度），第三层起直接透明（见下面 data-bg='on' 的规则）。
+   */
+  --bg-glass-inner: 0.3;
+  /* 面板的朦胧感（与壁纸自身的 --bg-blur 分开：那层给照片打底，这层给面板） */
+  --bg-blur-panel: 18px;

  /*
   * ─── 尺寸与动效 ───
@ -333,7 +347,8 @@
   */
  --bg-scrim: 0 0 0;
  /* 深色下面板要更实：背景亮部与深色卡片对比过强时，文字会显得发灰。 */
-  --bg-glass: 0.86;
+  --bg-glass: 0.66;
+  --bg-glass-inner: 0.34;

  /*
   * 深色下的层次靠「边框亮于底」而不是阴影。
@ -708,8 +723,33 @@ html[data-bg='on'] .bg-slate-100 {

 html[data-bg='on'] .bg-white {
  background-color: rgb(var(--c-white) / var(--bg-glass));
-  backdrop-filter: blur(16px) saturate(1.2);
-  -webkit-backdrop-filter: blur(16px) saturate(1.2);
+  backdrop-filter: blur(var(--bg-blur-panel)) saturate(1.2);
+  -webkit-backdrop-filter: blur(var(--bg-blur-panel)) saturate(1.2);
+}
+
+/*
+ * ★ 嵌在玻璃面板**里面**的面板不再各叠一次不透明度（2026-09-13 用户报的缺陷）。
+ *
+ * 相乘是这里的关键：两层 0.82 得 0.97、三层 0.995 —— 壁纸就是这么被吃掉的，
+ * 而且每层各做一次 16px 模糊，图案被糊成一片灰。
+ * 第二层只留一点色调（保住正文对比度），第三层起透明，且都**不再叠加模糊**。
+ */
+html[data-bg='on'] .bg-white .bg-white {
+  background-color: rgb(var(--c-white) / var(--bg-glass-inner));
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+}
+
+html[data-bg='on'] .bg-white .bg-white .bg-white {
+  background-color: transparent;
+}
+
+/* 侧栏里的玻璃面板同理：框架已经有一层底色，里面不能再叠。 */
+html[data-bg='on'] .bg-chrome-900 .bg-white,
+html[data-bg='on'] .bg-chrome-800 .bg-white {
+  background-color: rgb(var(--c-white) / var(--bg-glass-inner));
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
 }

 /* 悬停态也要接管：不接管的话鼠标一进面板就会闪成不透明（明显跳动）。 */
@ -719,12 +759,14 @@ html[data-bg='on'] .hover\:bg-gray-100:hover {
 }

 html[data-bg='on'] .bg-chrome-900 {
-  background-color: rgb(var(--c-chrome-900) / 0.86);
+  /* 框架也放宽一点：它是外层玻璃，占屏面积大，太实会把壁纸挡掉一大块。
+     里面的面板由下面「.bg-chrome-* .bg-white」那条接管，不会再叠一次。 */
+  background-color: rgb(var(--c-chrome-900) / 0.72);
  backdrop-filter: blur(16px) saturate(1.2);
  -webkit-backdrop-filter: blur(16px) saturate(1.2);
 }
 html[data-bg='on'] .bg-chrome-800 {
-  background-color: rgb(var(--c-chrome-800) / 0.82);
+  background-color: rgb(var(--c-chrome-800) / 0.68);
  backdrop-filter: blur(16px) saturate(1.2);
  -webkit-backdrop-filter: blur(16px) saturate(1.2);
 }
--- a/client/electron/src/main.tsx
+++ b/client/electron/src/main.tsx
@ -4,6 +4,8 @@ import App from './App';
 import { initTheme } from './stores/themeStore';
 import { initBackground } from './stores/backgroundStore';
 import './index.css';
+// 背景开启时要变半透明的浅色表面类（由 scripts/gen-background-takeover.mjs 生成）
+import './background-takeover.generated.css';;

 // 必须在 render 之前：晚一步就会让深色偏好的用户看到一帧白色闪屏。
 // index.html 里还有一段更早的内联脚本处理「JS bundle 到达前」那段空窗，
--- a/client/electron/test/background.test.mjs
+++ b/client/electron/test/background.test.mjs
@ -153,5 +153,53 @@ for (const f of readdirSync(compDir).filter(x => x.endsWith('.tsx'))) {
 }
 check('新组件未使用未映射色族', unmapped.length === 0, unmapped.join(' '));

+  // 16) ★ 玻璃不得层层相乘（2026-09-13 用户报："壁纸底上叠了太多不透明层"）。
+  //
+  // 判据用**算式**而不是感觉：每层都吃同一个 a，两层就是 1-(1-a)²。
+  // 缺陷时 a=0.82 ⇒ 两层 0.97、三层 0.995（壁纸在数学上被吃掉）。真实渲染实测
+  // （纯红壁纸读绿通道）同样印证：修复前 p95 82%，修复后 62%。
+  const varOf = name => {
+    const mm = css.match(new RegExp(`--${name}:\\s*([0-9.]+);`)); // 第一次出现 = 浅色那组
+    return mm ? Number(mm[1]) : NaN;
+  };
+  const glass = varOf('bg-glass');
+  const inner = varOf('bg-glass-inner');
+  const composite = (base, nested, layers) => {
+    let opaque = base;
+    for (let i = 1; i < layers; i++) opaque = opaque + nested * (1 - opaque);
+    return opaque;
+  };
+  const stacked = composite(glass, inner, 2);
+  check('玻璃有"嵌套层"变量', Number.isFinite(glass) && Number.isFinite(inner), `glass=${glass} inner=${inner}`);
+  check('有"嵌套面板不再各叠一次"的规则', /\.bg-white \.bg-white \{/.test(css));
+  check('两层嵌套后的有效不透明度 ≤ 0.85', stacked <= 0.85, `实际 ${stacked.toFixed(3)}`);
+  check('外层玻璃 ≤ 0.70', glass <= 0.7, `实际 ${glass}`);
+  check('判据自检：旧值 0.82 层层叠必须算得出 >0.95', composite(0.82, 0.82, 2) > 0.95);
+
+  // 17) ★ 浅色表面类的接管清单必须跟着源码走。
+  //
+  // 缺陷的另一半：当时只接管了 white/gray-50/slate-100，而源码里在用的
+  // gray-100(24 处)、blue-50(17)、red-50(13)… 全是实心的，正好把壁纸盖住。
+  const gen = read('../src/background-takeover.generated.css');
+  const used = new Set();
+  const walk = dir => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (/\.(tsx?|jsx?)$/.test(e.name)) {
+        const src = readFileSync(full, 'utf8');
+        for (const mm of src.matchAll(/bg-[a-z]+-\d{2,3}/g)) {
+          if (/^bg-[a-z]+-(50|100|200)$/.test(mm[0])) used.add(mm[0]);
+        }
+      }
+    }
+  };
+  walk(join(here, '../src'));
+  const PAGE_BASE = new Set(['bg-gray-50', 'bg-slate-100']); // 页面底必须保持全透明
+  const missing = [...used].filter(c => !PAGE_BASE.has(c) && !gen.includes(`.${c} {`));
+  check('源码里用到的浅色表面类全被接管', missing.length === 0, `漏了：${missing.join(', ')}`);
+  check('页面底没有被写进半透明清单', [...PAGE_BASE].every(b => !gen.includes(`.${b} {`)));
+  check('清单不是空跑（至少扫到 10 个类）', used.size >= 10, `实际 ${used.size}`);
+
 console.log(`\n背景：${pass} 通过${fail ? `，${fail} 失败` : ''}`);
 process.exit(fail ? 1 : 0);
--- a/client/electron/test/manual/wallpaper-layers-verify.mjs
+++ b/client/electron/test/manual/wallpaper-layers-verify.mjs
@ -0,0 +1,171 @@
+/**
+ * 壁纸到底有没有透出来 —— 量化判据（2026-09-13 用户报的缺陷）。
+ *
+ * 用户原话：「webui 目前在壁纸底上叠了太多不透明层，导致壁纸效果很差，几乎看不出来」
+ *
+ * # 怎么把它变成数
+ *
+ * 用**纯红壁纸（255,0,0）**，只看**绿通道**：面板是白的（绿 255）、壁纸是红的（绿 0），
+ * 于是某点合成后的绿色值 G = a·G_off ⇒ **a = G(开着) / G(关着)** 就是该处的
+ * 有效不透明度。同一个坐标取两次（背景开/关）就是天然的反向对照。
+ *
+ * 嵌套是相乘的，所以这个数直接暴露"叠了几层"：
+ *   一层 0.82 → 82%；两层 → 97%；三层 → 99.5%（缺陷现场就是 97% 以上）
+ * 用纯色壁纸是关键：backdrop-filter 的模糊对纯色不起作用，读数不受 blur 干扰。
+ *
+ * # 为什么自带 Chromium
+ *
+ * 原先走共享浏览器（CDP 9222）+ dist 注入，实测两条路都不通：
+ *   ① dist 注入后应用卡在 `phase='checking'`（bodyText 恒为「加载中」、整页 17 个元素）
+ *      ——量到的会是加载页而不是界面（这条已写成**前置断言**，不成立就不出结论）；
+ *   ② 共享实例标签页太多时 connectOverCDP 会挂住。
+ * 自带无头实例既避开这两条，也顺便做到"测自己这套 CSS、不打扰别人的标签页"。
+ *
+ * # 验的是哪份 CSS
+ *
+ * 从 `src/index.css` **原文**取 `html[data-bg='on']` 那几段注入到真实线上页面 ——
+ * 类结构没变（本次只改 CSS），所以注入等价于发布后的效果；也避免手抄走样。
+ *
+ * 用法：node test/manual/wallpaper-layers-verify.mjs
+ */
+import { readFile, mkdir } from 'node:fs/promises';
+// 走与 narrow-probe-helper 同一个入口（本机 playwright 装在 /usr/lib/node_modules）
+const PLAYWRIGHT = process.env.PLAYWRIGHT || '/usr/lib/node_modules/playwright/index.mjs';
+const { chromium } = await import(PLAYWRIGHT);
+
+const URL_ = process.env.APP || 'https://mail.jianfgit.xyz';
+const OUT = '/tmp/wallpaper-layers';
+await mkdir(OUT, { recursive: true });
+const RED = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAFUlEQVR4nGP8z8Dwn4GBgYGJAQ0AAB6nAgHh0m0iAAAAAElFTkSuQmCC';
+
+const css = await readFile(new URL('../../src/index.css', import.meta.url), 'utf8');
+const struct = [...css.matchAll(/html\[data-bg='on'\][^{]*\{[^}]*\}/g)].map((m) => m[0]).join('\n');
+// 变量也要注入：结构规则只是"用" var(--bg-glass)，不注入它就会继续读页面自带的旧值
+// ——实测漏了这一步时，"修复前/修复后"两组数字完全一样（都是页面里那个 0.82）。
+const first = new Map();
+for (const m of css.matchAll(/--bg-(glass-inner|glass|blur-panel|dim|blur):\s*[^;]+;/g)) {
+  if (!first.has(m[1])) first.set(m[1], m[0]);   // 第一次出现 = 浅色那组
+}
+const vars = `:root {\n  ${[...first.values()].join('\n  ')}\n}`;
+// 还要把**生成物**（浅色表面类的半透明接管清单）一起注入：那是这次修复的另一半
+// （gray-100 / blue-50 / red-50 … 这些原本是实心的）。
+const takeover = await readFile(new URL('../../src/background-takeover.generated.css', import.meta.url), 'utf8');
+const rules = `${vars}\n${struct}\n${takeover}`;
+console.log(`  注入：变量 ${first.size} 个 + 结构 ${struct.length} 字符 + 接管清单 ${takeover.length} 字符；含嵌套条 ${/\.bg-white \.bg-white \{/.test(struct)}`);
+
+const browser = await chromium.launch({ args: ['--no-sandbox'] });
+const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+await page.goto(URL_ + '/', { waitUntil: 'domcontentloaded', timeout: 30000 });
+await page.waitForTimeout(2500);
+if (await page.locator('input[autocomplete=username]').count()) {
+  await page.fill('input[autocomplete=username]', 'gui-lab');
+  await page.fill('input[type=password]', 'gui123456');
+  await page.click('button:has-text("登录")');
+  await page.waitForTimeout(3500);
+}
+const pre = await page.evaluate(() => ({ t: (document.body.innerText||'').slice(0,40).replace(/\n/g,'|'), els: document.querySelectorAll('*').length }));
+console.log(`  前置：元素 ${pre.els} 个，正文「${pre.t}」`);
+if (pre.els < 60 || pre.t.includes('加载中')) { console.log('  ✗ 前置不成立，终止（不给出结论）'); await browser.close(); process.exit(2); }
+
+await page.addStyleTag({ content: rules });
+await page.evaluate(() => {
+  const r = document.documentElement;
+  r.classList.remove('dark');
+  r.setAttribute('data-bg', 'on');
+  r.style.setProperty('--bg-dim', '0%');
+  r.style.setProperty('--bg-blur', '0px');
+});
+async function sample(bgImage) {
+  await page.evaluate((img) => {
+    const r = document.documentElement;
+    if (img) r.style.setProperty('--bg-image', `url("${img}")`), r.setAttribute('data-bg', 'on');
+    else { r.style.removeProperty('--bg-image'); r.setAttribute('data-bg', 'off'); }
+  }, bgImage);
+  await page.waitForTimeout(500);
+  const cdp = await page.context().newCDPSession(page);
+  const { data } = await cdp.send('Page.captureScreenshot', { format: 'png' });
+  await cdp.detach();
+  return page.evaluate(async (b64) => {
+    const img = new Image(); img.src = 'data:image/png;base64,' + b64; await img.decode();
+    const c = document.createElement('canvas'); c.width = img.width; c.height = img.height;
+    const ctx = c.getContext('2d'); ctx.drawImage(img, 0, 0);
+    const dpr = img.width / innerWidth, pts = [];
+    for (let y = 60; y < innerHeight - 60; y += 40)
+      for (let x = 60; x < innerWidth - 60; x += 40) {
+        const d = ctx.getImageData(Math.round(x*dpr), Math.round(y*dpr), 1, 1).data;
+        pts.push({ x, y, g: d[1] });
+      }
+    return pts;
+  }, data);
+}
+const off = await sample('');
+
+/** 面板点的有效不透明度分布（浅底的才算面板；暗色小控件故意不透明，不计入）。 */
+async function measure(label, rules) {
+  await page.evaluate((css) => {
+    document.querySelectorAll('style[data-probe]').forEach((n) => n.remove());
+    const st = document.createElement('style');
+    st.setAttribute('data-probe', '1');
+    st.textContent = css;
+    document.head.appendChild(st);
+    const r = document.documentElement;
+    r.classList.remove('dark');
+    r.setAttribute('data-bg', 'on');
+    r.style.setProperty('--bg-dim', '0%');
+    r.style.setProperty('--bg-blur', '0px');
+  }, rules);
+  const on = await sample(RED);
+  const panels = on
+    .map((p, i) => ({ x: p.x, y: p.y, gOn: p.g, gOff: off[i].g }))
+    .filter((p) => p.gOff >= 200);
+  const a = panels.map((p) => p.gOn / p.gOff).sort((x, y) => x - y);
+  const q = (r) => a[Math.min(a.length - 1, Math.floor(a.length * r))];
+  const stack = a.filter((v) => v >= 0.95).length / a.length; // 被吃光的比例
+  const sameCoord = panels.filter((p) => p.gOff >= p.gOn + 15).length / panels.length;
+  console.log(`  [${label}] 面板 ${a.length} 点：中位 ${(q(0.5) * 100).toFixed(1)}%  p90 ${(q(0.9) * 100).toFixed(1)}%  p95 ${(q(0.95) * 100).toFixed(1)}%  被吃光(≥95%) ${(stack * 100).toFixed(1)}%`);
+  return { a, stack, p95: q(0.95), p50: q(0.5), sameCoord };
+}
+
+const fixed = await measure('修复后', rules);
+
+// 对比度底线：换成近乎全黑的照片面，面板仍须是浅底（否则正文读不动）
+const DARK_PNG = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEklEQVR4nGNgYGD4z4AGGNEFAB0MAgHh0m0iAAAAAElFTkSuQmCC';
+const darkOn = await sample(DARK_PNG);
+const darkPanelG = darkOn.filter((p, i) => off[i].g >= 200).map((p) => p.g).sort((a, b) => a - b);
+// 取中位数而不是 p5：最暗的那 5% 混着徽标/边框/文字这些**故意**深色的元素，
+// 拿它们当"面板底"会得到一个假失败。中位数才是"典型面板"。
+const darkMidG = darkPanelG[Math.floor(darkPanelG.length / 2)];
+console.log(`  [深色照片面] 面板绿通道 中位 = ${darkMidG}（p5 ${darkPanelG[Math.floor(darkPanelG.length*0.05)]}）`);
+
+// 对照：把玻璃值改回缺陷时的样子（0.82，且没有"嵌套不再叠加"那几条）
+const before = rules
+  .replace(/--bg-glass:\s*0\.62;/g, '--bg-glass: 0.82;')
+  .replace(/html\[data-bg='on'\] \.bg-white \.bg-white( \.bg-white)? \{[^}]*\}/g, '');
+const regressed = await measure('修复前(0.82 且层层叠加)', before);
+
+const ok1 = fixed.p95 <= 0.85;
+const ok2 = fixed.stack <= 0.05;
+const ok3 = darkMidG >= 150;   // 深色照片面上，面板仍是浅底
+const ok4 = fixed.sameCoord >= 0.6;
+// 对照必须真的量出差别 —— 否则这条判据对这次改动毫无分辨力
+const ok5 = regressed.p95 - fixed.p95 >= 0.1;   // 旧值明显更实（0.82 vs 0.62）
+console.log('');
+console.log(`  ${ok1 ? '通过' : '失败'}  修复后面板 p95 ≤ 0.85（壁纸普遍透得出来）`);
+console.log(`  ${ok2 ? '通过' : '失败'}  ★ 修复后"被吃光"(≥95%) 的面板点 ≤ 5%`);
+console.log(`  ${ok3 ? '通过' : '失败'}  深色照片面上面板仍是浅底（绿中位 ≥150，正文对比度）`);
+console.log(`  ${ok4 ? '通过' : '失败'}  对照：关掉壁纸后同坐标更实 ≥60%`);
+console.log(`  ${ok5 ? '通过' : '失败'}  ★ 反向对照：改回旧值后面板明显更实（p95 差 ≥10 个百分点）`);
+await page.screenshot({ path: `${OUT}/20-fixed.png` });
+await page.evaluate((css) => {
+  document.querySelectorAll('style[data-probe]').forEach((n) => n.remove());
+  const st = document.createElement('style');
+  st.setAttribute('data-probe', '2');
+  st.textContent = css;
+  document.head.appendChild(st);
+}, before);
+await page.waitForTimeout(400);
+await page.screenshot({ path: `${OUT}/21-before.png` });
+const pass = [ok1, ok2, ok3, ok4, ok5].filter(Boolean).length;
+console.log(`\n壁纸层次：${pass} 通过，${5 - pass} 失败（截图 ${OUT}/20-fixed.png、21-before.png）`);
+await browser.close();
+process.exit(pass === 5 ? 0 : 1);