docs(lessons): §5.51 收回未证实的机理——hero 无条件黑底,null copy 造不出浅色版式

上一版把首页那条间歇红(actual 矮 3114px、整段换成另一套版式)归因到
`getHomePageCopy().catch(() => null)`。读回代码就知道这条解释站不住:
hero 是无条件 `bg-[#0B0A08]`,copy 为 null 只影响文案,产生不出「浅色无图 hero」。

改成如实记录:机理未取证,已确证的只有「同树隔离 3/3 绿、基线与被测代码一致 ⇒
环境侧偶发」。同时把修法写成可验证的状态判据(已落地):dwell + 排帧、
显影落定等待、截图前断言 data-cms-state;并写明没有采用 --workers=1 的理由
(用串行掩盖竞态、把 5 分钟的层拖到 17 分钟)。
This commit was merged in pull request #59.
This commit is contained in:
zhangxiang committed 2026-10-21 16:36:55 +08:00
1 parent ec30f508fa
commit 2c974d1971
1 file changed
+20 -18
+20 -18
View File
@@ -924,7 +924,7 @@ if [ "$A" -eq 0 ] && [ "$B" -eq 0 ]; then git add … && git commit … && git p
⇒ 通用判据:**跨路由的「等旧页退场再挂新页」不能依赖 framer 的 presence 状态机;
新页面挂载不得以旧页面的动画完成作为前置条件。**
### 5.51 视觉门禁的间歇红有两种签名:dwell 竞态与 CMS 取数退化,都不是像素回归(2026-10-20)
### 5.51 视觉门禁的间歇红有两种签名:装配竞态与整段换版式,都不是像素回归(2026-10-20)
**现象**:在 `3fabb77c` 上只读比对 `visual-regression.spec.ts`(本批未碰 `/team`、`/about/brand`
任何文件)得 **121 passed / 4 failed / EXIT=1**;紧接着原样重跑同一批用例,失败集合换了一批
@@ -943,28 +943,30 @@ expected 是已显影正文 ⇒ 内容停在 `opacity:0` 初始态,而不是
目标),但 IO 回调与 framer 的 `whileInView` 提交都要排帧;4 worker 抢 CPU 时 dwell 不够,
中间某屏就被跳过。判别实验:同一批用例 `--workers=1` 重跑 **10 passed / 0 failed / EXIT=0**。
**修法①**(只覆盖下面签名 1;独立动作,未随本批落地):dwell 提到 ≥250ms 且每步排空一帧
(`requestAnimationFrame`);或给 `ScrollReveal` 加一个「已显影」可查询标记供用例等待——
现在 `src/components/ui/scroll-reveal.tsx:80-96` 只透传 `className`,这条写不出来。
门禁口径:视觉层默认执行方式钉成 `--workers=1`,否则 `test:all` 里这一层可红可绿。
**修法(2026-10-20 已落地)**:`waitForPageStable` 的 dwell 120ms → 260ms 且每步排空
两帧;滚动结束后**再等一次「显影落定」**——`main` 下 inline `opacity:0`(framer 未提交的
初始态)且仍有高度的元素必须归零,超时直接把前 5 个 offender 的标签写进错误里,而不是
留给像素比对去猜。这条把关的是**状态**,不是时长,所以对 CPU 争用不敏感。
**补测(同日 22:20–22:35,同一棵树 `9ea8d5f4`)**:把整层改成 `--workers=1` 全量复跑,
得 **124 passed / 1 failed** —— 上面「串行即绿」的说法过强,必须更正。且那一条红
(`L2 主题切换 › 浅色主题 - 首页视觉` @ `visual-chromium-tablet`)在同一棵树上
`--repeat-each=3` 隔离复跑是 **3 passed**,在改动前的 `3fabb77c` 上单跑也是 passed。
⇒ 它是**负载相关的间歇红**,不是 worker 数目的函数。
**没有采用的方案**:把视觉层默认钉成 `--workers=1`。它能让读数稳定,但把 5 分钟的层拖到
17 分钟,是用串行掩盖竞态;竞态本身有确定的状态判据,就该按状态等。
**两种签名必须分开归因**(都不是像素回归):
1. **同高、带内空白**(`/team`、`/about/brand`):页高与基线一致,差异只在一条带内,
带内 actual 是 `opacity:0` 的空白 ⇒ `waitForPageStable` 的 120ms dwell 没把
`whileInView` 提交完。
带内 actual 是 `opacity:0` 的空白 ⇒ 120ms dwell 没把 `whileInView` 提交完(上面的修法覆盖它)。
2. **不等高、整段换版式**(首页 `theme-light-main` @ tablet):actual 比基线**矮 3114px**,
且带内不是空白而是**另一套版式**(浅色无图 hero、`还没有可以公开的成果` 占位区)。
根因在 `src/app/(marketing)/page.tsx:60` 的 `await getHomePageCopy().catch(() => null)`
——CMS 取数在负载下退化即静默回落成常量版式,页面照常 200、只是内容换了。
这一类**不能**用「加大 dwell」修,也不该由视觉基线去背。
**机理未取证,不要照抄一个像样的解释**:当时的怀疑是 `src/app/(marketing)/page.tsx` 里
`getHomePageCopy().catch(() => null)` 静默降级,但 hero 在代码里是**无条件黑底**
(`home-content-v16.tsx:101` 的 `bg-[#0B0A08]`),null copy 根本产生不出「浅色 hero」
⇒ 该解释被自己的代码读回否掉。已确证的只有:同树隔离复跑 3/3 绿、基线与被测代码一致
⇒ 环境侧偶发,不是提交引入。
收口方式因此改成**把状态显式化**而不是猜:首页现在输出 `data-cms-state`(`ok`/`empty`,
`page.tsx` 判定、`home-content-v16.tsx` 渲染),视觉层截图前先断言它——真退化会以
「CMS 数据退化:data-cms-state=empty」按名字失败。
⇒ 通用判据:**「串行复跑变绿」不足以给并行红背书,先比对签名再归因。**
同高空白带 = 装配竞态;不等高且内容换了一套 = 数据侧退化。判据实验是
「隔离复跑 N 次是否稳定 + actual/expected 的页高是否一致」,而不是「换一种并发就绿了」。
动基线之前这两步都要跑完,否则会把竞态或退化固化成参照。
同高空白带 = 装配竞态,用状态判据修;不等高且内容换了一套 = 先证伪自己的机理解释,
再决定是数据侧还是环境侧。判据实验是「隔离复跑 N 次是否稳定 + 页高是否一致 +
解释能否被代码读回」,而不是「换一种并发就绿了」。动基线之前这几步都要跑完,
否则会把竞态或一次偶发固化成参照。