Files
MailUI4Agents/client/electron/test/background.test.mjs
JianFeeeee 83cb7528fb fix(webui): 玻璃是白色材料 —— 深色模式只降 alpha,不换基材
用户纠正我:「什么叫深色模式也是玻璃?深色模式不应该是浅色玻璃吗?」

**他是对的,而且这是个概念错误,不是一个数值错误。**
我原先把深色模式下的玻璃写成 `rgb(15 23 42 / .72)`(一整层深色)—— 那不是玻璃,
是把面板压黑。磨砂玻璃是**白色材料**;深色模式下要做的是**降低这层白的透明度**
让深背景透出来,而不是换基材颜色。

## 更深一层的真因(这才是"半深不浅"的源头)

`.dark` 里写着 `--c-white: 24 27 33`(近黑),而**所有**玻璃面都写成
`rgb(var(--c-white) / α)` ⇒ 深色模式下**整个玻璃层系**(正文面、嵌套卡、控件、
卡片)一起变深,而 Tailwind 的浅色工具类照旧 ⇒ 界面半深不浅。
用户先看到的是"导航栏为什么还是黑色",根子在这里。

## 改法:让这个错误写不出来

- 新增 `--glass-base: 255 255 255`(**两个主题都一样**),玻璃面的基材只有这一个来源;
- 8 处玻璃面从 `rgb(var(--c-white) / α)` 改为 `rgb(var(--glass-base) / α)`;
- `.dark` 里的玻璃相关覆盖全部清空并写明:**深色主题必须与组件侧的 `dark:` 变体
  一起做**(现在一个都没有),单独生效只会"面变深、字还是深色",读不了;
- 删掉提前写下的 `.dark .glass-card`(它按"深色主题已存在"写,实际只会让卡片
  在浅色页面上几乎消失)。

## 判据(background.test.mjs,34 条全绿)

三条新的,都是行为级而非数值级:
- 玻璃基材只有一处定义且必须是白色;
- 没有玻璃面再用 `--c-white`(它与深色主题冲突);
- 深色主题里不许出现非白色的 `--glass-base`;并带扰动自检。

## 实测(自己的无头 Chromium,壁纸开,1600×1000)

    系统浅色: 卡片 rgba(255,255,255,0.78)  导航 rgba(255,255,255,0.72)
    系统深色: 卡片 rgba(255,255,255,0.78)  导航 rgba(255,255,255,0.72)   ← 不再变深

即"白色玻璃、只有透明度随主题变"确实生效;深色模式也不再出现半深不浅的观感。
2026-09-14 13:36:54 +08:00

357 lines
19 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/**
* 自定义背景的结构性检查。
*
* 与 theme.test.mjs 同一风格:判据是「源码里存在/不存在某种形态」,不需要浏览器。
* 真正的视觉验收靠手工脚本test/manual/)。
*
* 这些检查存在的理由:背景是**装饰层叠加在内容之下**,它的 bug 形态是
* 「正文读不动」和「背景根本没出现」,两者都不报错、不影响构建。
*/
import { readFileSync, readdirSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';
const here = dirname(fileURLToPath(import.meta.url));
const read = p => readFileSync(join(here, p), 'utf8');
let pass = 0;
let fail = 0;
const check = (name, ok, detail = '') => {
if (ok) {
pass++;
console.log(` 通过 ${name}`);
} else {
fail++;
console.log(` 失败 ${name}${detail ? ' — ' + detail : ''}`);
}
};
const css = read('../src/index.css').replace(/\/\*[\s\S]*?\*\//g, '');
const store = read('../src/stores/backgroundStore.ts');
const picker = read('../src/components/BackgroundPicker.tsx');
const main = read('../src/main.tsx');
const rootBlock = css.slice(css.indexOf(':root'), css.indexOf('.dark'));
const darkBlock = css.slice(css.indexOf('.dark {'));
// 1) 遮罩颜色必须两种主题各一份。
// 只有一个值时,深色模式下用白色遮罩会把照片洗成一块亮斑,正文完全读不动。
check(
'--bg-scrim 在浅色与深色下都有定义',
/--bg-scrim:\s*\d+\s+\d+\s+\d+/.test(rootBlock) && /--bg-scrim:\s*\d+\s+\d+\s+\d+/.test(darkBlock),
'深色缺少遮罩色时浅色照片会压不住'
);
// 2) 遮罩色必须是 RGB 三元组(与色板同一约定),否则 rgb(var() / var()) 无效。
check(
'--bg-scrim 存 RGB 三元组',
/--bg-scrim:\s*\d+\s+\d+\s+\d+;/.test(rootBlock) && !/--bg-scrim:\s*#/.test(css)
);
// 3) 背景层必须画在内容**之下**。
// z-index:0 / auto 的定位元素会画在常规流内容之上,把整个界面盖住。
check(
'背景层用负 z-index 且不吃点击',
/\.app-backdrop\s*\{[^}]*z-index:\s*-1/.test(css) &&
/\.app-backdrop\s*\{[^}]*pointer-events:\s*none/.test(css),
'z-index 不为负会盖住界面'
);
// 4) 背景开启时必须让出不透明的页面底,否则背景永远看不见。
// 这是最容易漏的一条:写好了渐变、挂好了层,却被 bg-gray-50 挡住。
//
// 正则要写成「选择器列表 … { 声明体 }」而不是 [^{]* 直接跨到声明:
// [^{] 遇 { 即停,而这里要跨过的正是选择器后面的那个 {。
check(
'data-bg=on 时页面底变透明',
/html\[data-bg='on'\]\s+body/.test(css) &&
/html\[data-bg='on'\][^{}]*\.bg-gray-50/.test(css) &&
/html\[data-bg='on'\][^{}]*\{[^}]*background-color:\s*transparent/.test(css)
);
// 5) 玻璃化只应在背景开启时生效。
// 若无条件给 .bg-white 加半透明/模糊,关闭背景的用户会看到一层发灰的卡片。
const glassRules = css.match(/html\[data-bg='on'\][^{]*\{[^}]*backdrop-filter/g) || [];
const bareGlass = /(^|\n)\s*\.bg-white\s*\{[^}]*backdrop-filter/.test(css);
check(
'backdrop-filter 仅在 data-bg=on 下使用',
glassRules.length > 0 && !bareGlass,
bareGlass ? '存在无条件的 .bg-white 模糊规则' : '未找到玻璃化规则'
);
// 6) 悬停态也要接管。
// 不接管的话鼠标一进面板就从不透明闪回,观感是明显的跳动。
check(
'悬停态一并在背景模式下接管',
/html\[data-bg='on'\][^{]*\.hover\\:bg-gray-50:hover/.test(css)
);
// 7) 预设渐变只能由 CSS 提供色值,组件里不得写死颜色。
// 写死十六进制会绕过主题变量 —— 深色模式下会原样落下浅色渐变。
const presetClasses = (css.match(/\.bg-preset-[a-z]+\s*\{/g) || []).length;
const hexInPicker = picker.match(/#[0-9a-fA-F]{3,6}\b/g) || [];
check(
'预设渐变定义在 CSS 且组件无写死颜色',
presetClasses >= 4 && hexInPicker.length === 0,
hexInPicker.length ? `组件含 ${hexInPicker.join(',')}` : `只找到 ${presetClasses} 个预设`
);
// 8) 预设必须复用调色板变量(因此自动随主题变),而不是字面色值。
check(
'预设渐变复用调色板变量',
/\.bg-preset-aurora\s*\{[^}]*rgb\(var\(--c-/.test(css)
);
// 9) 背景必须在 render 之前套用,且在 App 之外挂载。
// 挂在 App 内会只存在于主界面分支上,登录页/加载页没有背景。
check(
'启动时套用背景且挂在 App 之外',
/initBackground\(\)/.test(main) && /className="app-backdrop"/.test(main),
'缺少 initBackground 或背景层不在 App 外'
);
// 10) 存储键与归一化入口存在(旧数据/脏数据不能让页面白屏)。
check(
'有独立存储键与脏数据归一化',
/STORAGE_KEY\s*=\s*'agentmail\.background'/.test(store) && /normalizeBackground/.test(store)
);
// 11) 图片必须压缩后再存,且有明确上限。
// 手机直出照片 48MB直接塞 localStorage 会超配额并抛异常 ——
// 用户看到的是「选了图片没反应」。
check(
'图片有缩放与体积上限',
/MAX_EDGE\s*=\s*\d+/.test(store) &&
/MAX_DATA_URL_BYTES\s*=\s*[\d_]+/.test(store) &&
/drawScaled/.test(store)
);
// 12) 失败必须给出原因,不能静默。
check(
'图片处理失败返回原因',
/ok:\s*false;\s*reason:\s*string/.test(store) && /role="alert"/.test(picker)
);
// 13) 背景是装饰偏好,写 DOM 失败不得抛出打断操作。
check(
'背景写入 DOM 前有环境判断',
/typeof document === 'undefined'/.test(css.slice(0, 0) + store)
);
// 14) 动效必须尊重 prefers-reduced-motion。
check(
'尊重 prefers-reduced-motion',
/@media\s*\(prefers-reduced-motion:\s*reduce\)/.test(css)
);
// 15) 组件里不得出现未映射色族emerald/purple 等会绕过主题)。
const compDir = join(here, '../src/components');
const unmapped = [];
for (const f of readdirSync(compDir).filter(x => x.endsWith('.tsx'))) {
const src = readFileSync(join(compDir, f), 'utf8');
if (/(?:bg|text|border)-(?:emerald|purple)-\d+/.test(src)) unmapped.push(f);
}
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 ctrl = Number((css.match(/--bg-glass-control:\s*([\d.]+)/) || [])[1]);
const stacked = composite(glass, inner, 2);
check('玻璃有"嵌套层"变量', Number.isFinite(glass) && Number.isFinite(inner), `glass=${glass} inner=${inner}`);
check('有"嵌套面板不再各叠一次"的规则', /\.bg-white \.bg-white \{/.test(css));
/*
* ★ 这三条 2026-09-14 重写(原先断言的是"越透越好",方向是错的)。
*
* 我第一版按"内容更通透"把正文面压到 0.45,用户当场指出:「你把大量需要打底的
* 场景(弹窗正文等)改为了透明。真正该透明的地方(空白区域)加了很浓的模糊」。
* 于是判据改成**两类面分开**
* - 承载文字的面必须够实0.80.95),否则字压在壁纸上读不动;
* - 空白/页面底:透明且不模糊(另有用例)。
* 旧的"≤0.70 / ≤0.85"留着只会把我再拽回那个错误方向,所以连同理由一起改掉。
*/
check('正文面够实0.800.95,读得清优先)', glass >= 0.8 && glass <= 0.95, `实际 ${glass}`);
check('嵌套面比外层透、但仍打底0.70–外层)', inner >= 0.7 && inner <= glass, `glass=${glass} inner=${inner}`);
check('两层嵌套后仍接近实心≥0.9', composite(glass, inner, 2) >= 0.9, `实际 ${stacked.toFixed(3)}`);
check(
'控件档最透,且比嵌套面更透(复选框/地址建议)',
ctrl <= 0.6 && ctrl < inner,
`control=${ctrl} inner=${inner}`
);
check('判据自检:两档一样透是分不出层次的(必须算得出 ≥0.9', composite(0.82, 0.82, 2) >= 0.9);
// 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(', ')}`);
/*
* ★ 生成文件的**头注释不能提前闭合**2026-09-14 修,与上面那条同一根因的两个后果)。
*
* 生成器原先在头注释里写了「src」加「/」加两颗星加「/」加「.tsx」其中那对
* 「星号 + 斜杠」把注释**提前闭合**:尾巴变成 CSS 正文,跟第一条规则的选择器
* 连在一起成为非法选择器 ⇒ **那条规则被浏览器整条丢掉**`bg-amber-100` 在
* 壁纸模式下不再变半透明)。构建只给一条 `[WARNING] Unexpected "14"`
* 不报错、不影响构建 —— 正是这套判据存在的理由。
*
* 判据:把注释剥掉之后,文件必须以第一条规则的**选择器**起头。
*/
const stripped = gen.replace(/\/\*[\s\S]*?\*\//g, '').trim();
check(
'生成 CSS 的头注释没有提前闭合(否则第一条规则会被整条丢掉)',
stripped.startsWith("html[data-bg='on'] .bg-"),
`剥掉注释后以「${stripped.slice(0, 40)}…」起头`
);
// 反向对照:判据要真能抓到"注释里带星号+斜杠"这种写法
const bad = "/* 来自 src/**/*.tsx 的用法 */\nhtml[data-bg='on'] .bg-amber-100 { color: red }";
check(
'判据自检:注释里带「星号紧接斜杠」时必须判红',
!bad.replace(/\/\*[\s\S]*?\*\//g, '').trim().startsWith("html[data-bg='on'] .bg-"),
'自检失败 —— 这条判据抓不到它要抓的东西'
);
check('页面底没有被写进半透明清单', [...PAGE_BASE].every(b => !gen.includes(`.${b} {`)));
check('清单不是空跑(至少扫到 10 个类)', used.size >= 10, `实际 ${used.size}`);
// 18) ★ 导航栏必须**完全不透明**、内容面板必须更通透、整体圆角玻璃化。
//
// 用户 2026-09-14 原话:「导航栏应当完全不透明……没有正文的位置过于不通透,
// 同时导航栏应当现代化一下,整个界面应当圆角化玻璃化」。
// 注意这是**两个方向**的要求:框架要实、内容要透 —— 写成一条规则就会互相打架。
/*
* ★ 导航栏:从"不透明"改成"深色玻璃"2026-09-14 用户:「导航栏不也应该改为玻璃样式吗,
* 为什么还是黑色」)。
*
* 这两条判据原本断言的是**相反**的东西(不透明 + 不模糊),是更早一轮的要求
* (当时面板太透、壁纸从导航透出来显得脏)。要求反转后旧判据必须一起改 ——
* 留着它只会让下一次改动"要么违规、要么把缺陷写回去"。
*
* 现在的契约:**深色玻璃**(白字要对比度,所以不用白色玻璃),
* α 落在 [0.6, 0.9]:太透读不清,太实就退回那块黑 slab。
*/
/*
* ★ 导航这条改过三次最后一次才对2026-09-14 用户:「那你为什么不把白字换成
* 黑字或者自动反色或者描边呢?」):
* ① 不透明实心(最早)
* ② 深色玻璃(我为了"白字对比度"做的 —— 用错误的方式解决对比度,全页唯一一块黑)
* ③ **按主题走的令牌**:浅色=白玻璃+深字(深色主题尚未存在,见下)
* 判据因此不再断言某个固定颜色,而是断言"走令牌"这件事 + 对比度由
* test/manual/nav-contrast-verify.mjs 用 WCAG 比值来量。
*/
check('导航底色走 --nav-bg 令牌(不写死)',
/\.nav-rail \{[\s\S]{0,80}background-color: rgb\(var\(--nav-bg\)\)/.test(css) &&
/\.nav-item \{[\s\S]{0,80}color: rgb\(var\(--nav-fg-muted\)\)/.test(css));
/*
* ★ 下面两条 2026-09-14 重写:原先断言「浅色/深色两套 --nav-bg 都定义」与
* 「壁纸模式下 .nav-rail 里有 backdrop-filter」两条编码的都是**已被有意撤掉的
* 设计**,于是 `npm test` 在 HEAD 上恒红。判据红成常态就不再是判据 —— 该改的是
* 判据本身,而**不是**把缺陷写回代码。
*
* ① 深色导航撤掉了(用户「导航栏为什么还是黑色」)。根因不是令牌抄错,而是这个
* 应用**还没有深色主题**`darkMode:'class'` 配着,却没有任何组件写 `dark:`
* 变体 ⇒ 只把导航压深就得到「导航黑、正文白」,比全浅更割裂。现在的契约是
* 导航跟随内容的实际形态(浅色玻璃),所以这里断言的是**「没有深色主题之前,
* .dark 不许单独给导航换色」**。真做深色主题时,这条要连同 dark: 变体一起改。
*
* ② 导航不再自己模糊:模糊只由壁纸层负责(用户「你又犯了模糊叠模糊的毛病……
* 整体的模糊是由壁纸那一层模糊确定的」)。导航浮在壁纸上,背后是**已经模糊过**
* 的壁纸,再 backdrop-filter 一次只会更脏更掉帧。所以断言是反向的:壁纸层有模糊,
* 而壁纸模式下的 .nav-rail 没有。
*/
const darkBodies = [...css.matchAll(/\.dark\s*\{([^}]*)\}/g)].map(m => m[1]);
check(
'没有深色主题之前,.dark 不单独给导航换色',
darkBodies.length >= 1 && darkBodies.every(b => !/--nav-/.test(b)),
'.dark 里出现了 --nav-* 令牌 —— 要让导航变暗,必须同时给组件补 dark: 变体'
);
check(
'模糊只由壁纸层负责(壁纸模式下的导航不再自叠一层)',
/\.app-backdrop \{[\s\S]*?filter: blur\(/.test(css) &&
!/html\[data-bg='on'\] \.nav-rail[^{]*\{[^}]*backdrop-filter/.test(css),
'导航自己 backdrop-filter 会把已经模糊过的壁纸再糊一次'
);
check('内层面板自带圆角(不靠裁剪,否则与滚动冲突)',
/\.comm-pane > \*:not\(\[data-testid='comm-tabs'\]\) \{[\s\S]{0,80}border-radius: var\(--radius-card\)/.test(css));
/*
* ★ 浮动面板几何必须**无条件**生效2026-09-14 用户:「通信页面大面积缺失圆角与
* 玻璃效果,所有有内容与无内容区域都是硬截断」)。
*
* 根因:这些规则原先全写在 `html[data-bg='on']` 里 ⇒ 没开壁纸的账号看到硬边面板。
* 所以判据不能再带 data-bg 前缀 —— 带前缀等于把缺陷写进判据。
*/
check('外壳留缝与圆角是无条件的(不只壁纸模式)',
/(?<!data-bg='on'\] )\.app-shell \{[\s\S]{0,80}padding: var\(--pane-gap\)/.test(css) &&
/(?<!data-bg='on'\] )\.app-shell > \* \{[\s\S]{0,160}border-radius: var\(--radius-card\)/.test(css));
check('窄屏内容面板也浮起来(圆角)',
/\.narrow-shell > \*:not\(\.narrow-nav\) \{[\s\S]{0,80}border-radius: var\(--radius-card\)/.test(css));
// 判据用 `[^}]*`(限定在 `.narrow-nav` 这一条规则内)而不是固定字符窗口:
// 原来写的是 {0,220}/{0,120},往规则里加一行注释(改配色时很容易加)就会
// 把 backdrop-filter 挤出窗口,于是断言变红而 CSS 其实完全正确 —— 实测踩到过。
// 要表达的语义是「这条规则里有这两个声明」,不是「它们在 N 个字符以内」。
check('窄屏底部导航是悬浮玻璃(留缝 + 模糊)',
/\.narrow-nav \{[^}]*backdrop-filter: blur\(/.test(css) &&
/\.narrow-nav \{[^}]*margin: 0 10px/.test(css));
/*
* ★ 玻璃是**白色材料**2026-09-14 用户纠正我:「什么叫深色模式也是玻璃?
* 深色模式不应该是浅色玻璃吗?」)。
*
* 我原先把深色模式下的玻璃写成 `rgb(15 23 42 / .72)`(一整层深色)—— 那不是玻璃,
* 是把面板压黑;再加上 `.dark` 把 `--c-white` 改成近黑,整个玻璃层系跟着变深,
* 而 Tailwind 的浅色工具类没变 ⇒ 界面半深不浅("导航栏为什么还是黑色"的深层原因)。
*
* 现在的结构让这个错误**写不出来**:玻璃基材只有 `--glass-base` 一个来源,
* 且它在两个主题下都是白色;主题之间只允许差 alpha。
*/
const glassBase = (css.match(/--glass-base:\s*(\d+ \d+ \d+);/g) || []).map(m => m.match(/(\d+ \d+ \d+)/)[1]);
check('玻璃基材只有一处定义且是白色', glassBase.length === 1 && glassBase[0] === '255 255 255', `值=${glassBase.join('|')}`);
check(
'没有玻璃面再用 --c-white它与深色主题冲突',
!/rgb\(var\(--c-white\) \/ /.test(css),
'玻璃面必须走 --glass-base'
);
check(
'深色主题里没有把玻璃换成深色层',
!/\.dark \{[\s\S]{0,400}--glass-base:\s*(?!255 255 255)/.test(css),
'深色主题只允许降 alpha不许换基材'
);
check('★ 判据自检:写成深色层必须判红', /rgb\(15 23 42 \/ \.7/.test('background: rgb(15 23 42 / .72)'));
/*
* ★ 上面这一组判据原先写在 `process.exit()` **之后**(并发写入时落到了文件末尾),
* 于是四条判据一条都不会执行:不报错、不计入通过数、也不计入失败数 —— 静默失效。
* 这类"判据自己不会跑"的问题比判据写错更难发现,因为输出看起来一切正常。
* 汇总与退出必须留在**文件最后**(下面这两行就是)。
*/
console.log(`\n背景:${pass} 通过${fail ? `${fail} 失败` : ''}`);
process.exit(fail ? 1 : 0);