/** * 自定义背景的结构性检查。 * * 与 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) 图片必须压缩后再存,且有明确上限。 // 手机直出照片 4–8MB,直接塞 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.8–0.95),否则字压在壁纸上读不动; * - 空白/页面底:透明且不模糊(另有用例)。 * 旧的"≤0.70 / ≤0.85"留着只会把我再拽回那个错误方向,所以连同理由一起改掉。 */ check('正文面够实(0.80–0.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('外壳留缝与圆角是无条件的(不只壁纸模式)', /(? \* \{[\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);