agentcss 0.0.0-stage → 0.11.3

package/docs/INVARIANT.md

@@ -0,0 +1,372 @@
+# 不变式（Invariant）
+
+> **这一层里写的不是「给 AI 定的规矩」，是「客观事实」。**
+> 因此它**不会**因为模型变强而失效，也不需要"以后放宽"。
+
+---
+
+## 🔴 先读这条：写在这里，**不等于**它就是事实
+
+**位置不代表正确性。** 一条内容进了这份文件，只说明写下它的那一刻，
+我们认为它经得起下面这一问（"无限强的模型成立吗"）。
+
+判据就两条，任一条不成立 ⇒ 改它，或把它挪到它该去的层：
+
+1. 它描述的是 **CSS / DOM / API 的机制**，还是**某一类体系的做法**？只有前者属于这层。
+   后者要么有自己的作用域（写清楚是哪类体系），要么属于 Contract / Guidance。
+2. 它的**作用域**写清楚了吗？「在某类结构里成立」必须写明是哪类。
+   不写 ⇒ 会被读成普遍禁令；而大多数被抱怨"这条太绝对"的内容，
+   缺的从来不是结论，是作用域。
+
+最近一次复核据此处理了四条：事实部分保留，把推论中"对所有情况都成立"的那部分
+改成**带作用域**的说明（改动痕迹见各自的「作用域 / ⚠️」段落）。
+
+⇒ 发现这里写错了，**就地改**。「它在 INVARIANT 里」不是不去核的理由 ——
+恰恰相反，正因为别处的规则都引用它，错的代价才最大。
+
+---
+
+## 为什么要单独分出这一层
+
+一个真实的架构悖论：
+
+> 今天为了让 AI 少犯错而加的约束，明天可能变成更强的 AI 的天花板。
+
+这个悖论之所以成立，是因为**大多数"约束"其实是给当前模型能力打的补丁**：
+模型不会规划 ⇒ 那就规定它必须按步骤走；模型不会看全局 ⇒ 那就禁止它改全局。
+
+模型一旦变强，这些补丁就从"护栏"变成"牢笼"。
+
+**解法不是"以后再说"，是分层。** 只有把「事实」和「补丁」分开，
+补丁才能被安全地摘掉，而事实一个字都不用动。
+
+| 层 | 是什么 | 会不会变 | 谁负责 |
+|---|---|---|---|
+| **Invariant**（本文件） | 客观事实 | **永不变**（除非 CSS 规范变了） | 门禁 |
+| **Contract**（`ai/contract.schema.json`） | 版本化的接口约定 | 随版本变，**向后兼容** | 校验器 |
+| **Guidance**（`docs/GUIDANCE.md`） | 当前模型下的工作建议 | **随时可变，可整份推翻** | 人 |
+
+⇒ **判断一条内容该放哪层的唯一标准**：
+> 如果明天出现一个无限强的模型，这句话还成立吗？
+> 成立 ⇒ Invariant。不成立 ⇒ Guidance。
+> 是"我们约定好接口长这样" ⇒ Contract。
+
+---
+
+## 一、作用域类事实
+
+### I-1 裸标签选择器的作用域是**整个文档**
+
+```css
+a { color: red }        /* 命中文档里每一个 <a>，无论它属于谁 */
+```
+
+这是 CSS 的定义，不是我们的规定。
+
+**推论**：在一个"我们不拥有整个文档"的库里写裸标签选择器，
+等价于**修改使用者的页面**。与谁在写这行代码无关，与模型强弱无关。
+
+- 门禁：`bleed-gate.py`
+- 已发生的事故：`03-patterns/content/content.css` 曾有 `a { color: var(--accent) }`，
+  把宿主全站链接染色。已修。
+
+### I-2 页面级 override 链的复杂度是**单调递增**的
+
+```css
+.slide-3 h1 { ... }     /* 第 1 次局部调整 */
+.slide-4 h1 { ... }     /* 第 2 次 */
+.slide-3 .card h1 { ... }/* 发现冲突，加码 */
+```
+
+每加一层特异性，就**只能再加一层**来覆盖它。
+这不是"AI 容易犯的错"，是**特异性机制的必然结果**。
+
+**推论（作用域限定）**：在**存在唯一汇聚点**的体系里，改汇聚点优于在页面里逐处加特异性 ——
+因为前者一处生效、全量跟随，后者每一处都要再同步一次。
+
+⚠️ 这条**不**等价于"任何页面都不许有局部样式"。
+在不拥有汇聚点、或改动本就只影响一个页面的场景里，局部样式是直接表达意图的方式；
+它付出的代价是"改一处时这一处不跟随"，而不是"这么写就错了"。
+
+### I-3 未分层样式**永远**赢过已分层样式
+
+`@layer` 的层序优先于选择器特异性。
+（这也是为什么 Web Awesome 把全局样式分层——让使用者的 CSS 自动赢，不需要 `!important`。）
+
+- 本库未使用 `@layer`。理由、切换前提与就绪判据见 `docs/BENCHMARK.md` 的「级联分层的决定」一节。
+
+### I-4 inline style 的优先级高于**一切**样式表
+
+`element.style.setProperty('--surface', x)` 会压掉使用者样式表里的 `--surface`，
+使用者只能再加 `!important` 反击。
+
+- 过去的代价：强制暗色曾靠 JS 往 `:root` 写 30 条 inline 属性实现，
+  等于把整个配色层抬到样式表之上。
+- 现已消除：暗色由 CSS 表达（`[data-theme="dark"]`），JS 不持有任何色值。
+
+---
+
+## 二、令牌类事实
+
+### I-5 绕过令牌的颜色在令牌切换时**必然**失效
+
+```css
+.card { background: #FFFFFF }   /* 令牌切换对它没有任何作用 */
+```
+
+不是"可能不好看"，是**切换机制对它没有任何作用**——它根本没引用令牌。
+
+**作用域**：这条只在**颜色由令牌驱动切换**的系统里成立。
+一个没有令牌切换机制的页面里写死颜色，不受这条约束 ——
+它付出的代价是"将来接入切换机制时这一处不跟随"，不是"现在就错了"。
+
+- 门禁：`hardcode-gate.py`
+- 例外判据（写死在门禁里）：**判断"这是内容色还是效果色"**。
+  阴影是光影效果，不是主题内容 ⇒ 允许裸值。内容底色 ⇒ 必须令牌。
+  已发生的事故：把 `switch.css` 的阴影也改成令牌，反而是错的。
+- ⇒ 反过来说：**并非所有固定颜色都错**。只有"本该跟随主题的内容色"才必须引用令牌；
+  效果色、数据可视化里承载语义的色标、品牌固定色，都有各自的固定取值理由。
+
+### I-6 `tokens.css` 是全库配色/间距/字号的**唯一汇聚点**
+
+改它的影响面 = 全库。这是依赖拓扑的结果。
+
+- 门禁：`impact-report.py` —— 它把"改了什么 ⇒ 必须重跑什么"机械化，
+  **不靠人判断**。
+
+### I-7 令牌有第二份真值来源 ⇒ 必然漂移
+
+两份手写的值**都能各自自洽**，所以**测不出来**，只会慢慢错开。
+
+- 实证：`theme-toggle.js` 第一版手写的 20 个暗色令牌，17 个与 tokens.css 不一致，
+  连名字都编错（`--warn` / `--danger-soft`，真名 `--warning` / `--danger-bg`）。
+- 缓解：真值只有一份，其余**全部生成**（`theme-sync.py`）+ `--check` 门禁。
+- 已根治的实例：暗色不再由 JS 持有值——CSS 自己表达，JS 只翻属性。
+
+---
+
+### I-16 自定义属性的 `var()` 在**声明它的元素**上就求值完毕，后代拿到的是结果
+
+这条是 P1（容器级主题）首跑实测撞出来的，和 I-7 是同一个根的两面：
+
+```css
+:root { --raw-paper: #f6f7f8;  --paper: var(--raw-paper); }
+
+.dark { --raw-paper: #14171A; }   /* 只覆盖 L1 */
+```
+
+`.dark` 里的 `--paper` **仍然是 `#f6f7f8`**。原因不是特异性、不是顺序：
+`--paper` 的声明在 `:root` 上，它的 `var(--raw-paper)` 在**那里**就替换完了，
+后代继承的是替换后的值。覆盖 `--raw-*` 只影响"在本元素上求值"的那些声明。
+
+- 实证：改造前实测，暗区容器 `--paper` 与区外一字不差（`#f6f7f8`），
+  按钮底色也完全没变（`rgb(27,77,143)` 两边相同）。
+  补上 `--paper: var(--raw-paper)` 到作用域块之后，才变成 `#14171A` /
+  `rgb(122,169,222)`。
+- 推论一：**"两层令牌 + 一处覆盖"不会自动获得作用域能力**。
+  每多一个作用域，L2 别名就要跟着重声明一次 —— 这是 CSS 的规定动作，不是实现选择。
+- 推论二：这也意味着 L1/L2 分层的收益（换肤只改一处、暗色不会漏）**只在
+  `:root` 上成立**；一旦要局部换肤，那份"重声明"就必然出现第三份真值
+  ⇒ 只能交给生成器 + 门禁（I-7 的老结论）。
+- 推论三：`revert` / `unset` 都**不能**"回到上一层作用域"。
+  自定义属性在 UA 样式里不存在 ⇒ `revert` 得到"未定义"（`var()` 走兜底或失效），
+  `unset` 对自定义属性等同 `inherit` ⇒ 拿到的还是上一层的值。
+
+## 三、状态表达类事实
+
+### I-8 写在 DOM 属性上的状态，其**存在不依赖 JS 执行过**
+
+| 写法 | 谁能读到 | 改坏了 JS 之后 |
+|---|---|---|
+| `data-state="closed"` | 任何人、任何工具、任何时刻 | 值还在那儿，可被断言、可被门禁检查 |
+| 状态类名（由 JS add/remove） | class 本身可读、可被选择器命中、可被测试断言 —— 但要等 JS 执行过才存在 | class 消失，CSS 规则还在 ⇒ **静默错乱，无报错** |
+
+⚠️ 两者的区别**不是**"class 不可读 / 不可测试"：class 完全可读、可被选择器命中、
+可被断言，这一点没有争议。真正的区别是**状态的存在是否依赖 JS 曾经正确执行过** ——
+属性写进 HTML 就在那儿，类名要等 JS 跑。
+⇒ 因此风险的性质是**耦合**（状态与 JS 实现绑在一起），不是"不可观测"。
+
+**这是 PPT 事故的技术根因**：状态不在 DOM 里 ⇒ 无法从文档反推当前状态 ⇒
+每次局部修改都是在看不见状态的情况下盲改 ⇒ 改 A 坏 B。
+
+**实证（比"理论上有风险"更硬）**：本库曾长期两套并存——CSS 同时写
+`.tooltip` 的状态类与 `[data-state="open"]`，但 JS 只加前者。后果有两层：
+
+1. 文档告诉使用者"请改用 `data-state`"，而**这个分支从来不会被设上** ⇒
+   承诺了一个不工作的 API；
+2. 一次半自动改写把 `.a.is-disabled .b` 拆成 `.a.is-disabled, .a[data-state] .b`
+   ⇒ 前半截**丢了后代选择器**，规则落到容器自己身上，真正该变灰的 `.b`
+   再也没有这条样式。**这个 bug 已随发布版本出去了**，且不报错、页面照常显示。
+
+- 已整改：`is-*` 归零，状态一律走属性（详见 `API.md` 的迁移表）。
+- 教训：**两套表达不是"冗余"，是"其中一套必然是死的，而且没人看得出来"。**
+
+### I-9 枚举字符串能表达的状态数**严格多于**布尔
+
+`data-state="open" | "closed"` 可以表达第三态（`closing`——动画中）。
+`isOpen: boolean` 不能。
+
+⇒ 这不是风格偏好，是**表达能力的客观差异**。
+
+⚠️ 但不能反推成"用布尔就是错的"：二态场景（开/关、有/无、选中/未选中）
+用 boolean 本身不是技术错误，它只是**在需要中间态时不够用**。
+⇒ 判据是**这个状态有没有第三个取值**（如"动画中""加载中""部分选中"），
+而不是"一律不许用布尔"。
+
+---
+
+## 四、验证类事实
+
+### I-10 一个"报告通过但什么都没检查"的门禁，比没有门禁更危险
+
+没有门禁 ⇒ 你知道要自己看。
+假绿门禁 ⇒ 你以为有人在看。
+
+- 实证 1：`es5-gate.py` 传 `--dir` 时扫 **0 个文件**，却报 PASS。
+  它源码第 98–103 行自己就写了这个警告，但调用方一直传 `--dir`。
+- 实证 2：`shot-baseline.py` 一张图都没截到，报 `OK 23 / 0 个页面观感一致`。
+- 实证 3：`api-snapshot.py` 注入 `Select.destroy()` 幻觉 API，仍报 OK。
+- 实证 4：16 个门禁用 `--dir .`，扫进了 `node_modules`。
+- 实证 5：**代码说自己会检查，但没有任何门禁跑它**。
+  `adapters/presentation/check.js` 声称守五条呈现判据（版面登记 / 单页上限 /
+  必须有标题 / 层级不跳级 / 禁页面级选择器），而 `core-boundary` 只验了
+  `to-doc.js` 的往返 ⇒ `check.js` **一次都没被执行过**。
+  读 README 的人会以为有人在看，实际上没人看 —— 这就是假绿的一种，
+  而且是最难发现的一种：**它不产出任何报告**。
+  ⇒ 修法：`presentation` 门禁对合规 / 违规两份 fixture 实跑，
+  要求五条判据**各命中一次**，并带反向控制（弄瘫判据 ⇒ 门禁必须认出它失效）。
+- 实证 6：**门禁在测另一棵树**。视觉回归用固定端口起静态服务，
+  端口被占时子进程**立刻静默退出**，而 `Popen` 不报错、返回值正常
+  ⇒ 截图全部打到了另一个目录的残留服务上。
+  之所以被发现，是**修好了 CSS 之后 diff 数字一字未变**。
+  ⇒ 修法：改用操作系统分配端口（bind 0）+ canary 校验（拉文件与磁盘字节比对）。
+- 实证 7：**门禁的取文件清单只取"已跟踪"的文件**。
+  新生成的产物目录还没进索引时，六道内容门禁**一个文件都看不见**
+  ⇒ 本地全绿 ⇒ 提交 ⇒ 干净克隆里跑 ⇒ 立刻红。
+  未跟踪文件恰恰是最需要被看的（那是刚写完的新代码），却被排除在视野外。
+  ⇒ 修法：取文件清单 = 已跟踪 ∪ 未跟踪且未被忽略（见共享模块的取文件函数）。
+  ⇒ 反向控制：新建一个**未跟踪**的违规文件（旧视野下它 0 命中、新视野下必须被抓住）。
+- 实证 8：**判据只数了"初始状态"，没制造状态变化**。
+  给树新加一条"整棵树只能有一个 `tabindex="0"`"，第一版只数**页面加载完那一刻**；
+  把实现里"移动前把其余置 -1"那行删掉后，它**依然全绿**（因为那一行只在按键后才起作用）。
+  ⚠️ 最迷惑的地方：它不是"判据写错了"，是**判据根本没跑到被测的那段代码** ——
+     报告里照样写着 PASS，和真绿长得一模一样。
+  ⇒ 修法：判据**自己先把状态跑起来**（移动 → 收起 → 再移动 → 再展开），再断言。
+  ⇒ 反向控制：删掉那一行 ⇒ 实测 1 个 0 变成 7 个 0，判据红了。
+  ⇒ 推论：**凡是"检查某个不变量"的判据，都要先问一句"我有没有真的走到会破坏它的那条路径"**。
+
+- 实证 9：**"跟源码一致"本身可以是假的** —— 契约文件是**生成**出来的。
+  注入 emit 核之后，生成器用 `window\.([A-Z]\w*)\s*=` 抽组件暴露的全局名，
+  而核里有 `typeof window.CustomEvent === 'function'`
+  ⇒ `===` 的**第一个** `=` 被当成赋值 ⇒ **10 个组件的 global 全变成 `CustomEvent`**。
+  ⚠️ 为什么全绿：这道门禁的判据是「契约 == 生成器重跑的结果」，
+     而生成器**正是**那个写错的东西 ⇒ 自己跟自己对答案，永远一致。
+     干净克隆跑完全套门禁也是 EXIT=0（条数不写死 —— 由 `doc-facts-gate.py`
+     从 `check-all.sh` 实算，见它自己打印的注册数）。
+  ⇒ 教训：**生成出来的契约，不能只跟"生成器再跑一遍"比** —— 那没有引入任何新信息。
+     它必须挂在**另一根独立的桩**上（本例：浏览器实测的全局名单）。
+  ⇒ 修法：正则改 `=(?!=)`；抽取前先摘掉 `BEHAVIOR INJECT` 块（核不是组件的源码）；
+     并新增判据「声明的 global 必须在浏览器里真探得到」（`api-form` 判据 4，
+     含反向控制，`CustomEvent` 是它的**事故真值反例**）。
+
+- 实证 10：**反向控制自己也可能"没跑到被测的那段代码"**。
+  给 `api-form` 加判据 5（注释里承诺的 API 必须真实存在）时，
+  反向控制只喂了**判定函数**合成数据 ⇒ 四条全绿；
+  而**扫描函数**第一版的别名正则用了非捕获组 `(?:Select|Pagination)`
+  ⇒ `m.group(2)` 直接 `IndexError` —— 真跑起来必崩，自检却一点没提。
+  ⚠️ 形状与实证 8 完全一致，只是这次"没跑到"的是**反向控制自己**：
+     反向控制绿 ⇒ 大家以为判据有牙，实际它一跑就崩。
+  ⇒ 修法：把被测函数拆成**纯函数**（不读文件、不起浏览器），
+     反向控制直接喂合成输入 ⇒ 扫描与判定**各自**都有反例。
+  ⇒ 推论：**写完反向控制，要再问一句"它有没有真的调用到被测的那个函数"**。
+
+⇒ **因此本库每一道新门禁都必须做反向控制**：注入反例，证明它会红。
+**没有反向控制的门禁不算门禁。**
+⇒ 另外：**门禁依赖的每一份输入都要能被证明是"本次的"** ——
+   端口、临时目录、缓存文件，任何一个指向别处，报告再漂亮也是假的。
+
+### I-11 解析 CSS/HTML 时，正则不是解析器
+
+- 实证：`prefix-build.py` 第一版把 `this.tablist` 当成选择器 `.tablist` 改写 ⇒ `SyntaxError`。
+- 缓解：改写后对所有 JS 跑 `node --check`；选择器规则加 `(?<![\w$])` 前缀约束。
+
+### I-12 浏览器不认识的声明、悬空的 `var()` 引用 ⇒ **静默失效**
+
+写错属性名**不报错、不告警、不影响后续解析**：整条声明被丢弃，其余照常生效。
+`var(--x)` 里的 `--x` 从未定义且没有兜底 ⇒ 该声明在**计算值阶段**无效，整条丢弃。
+
+- 实证：全库 19 处写了 `border-inset-inline-start` / `-end` ——
+  这不是一个存在的 CSS 属性（正确的是 `border-inline-start` / `-end`）。
+  机械验证：`CSS.supports()` 两种形式与 `element.style.setProperty()` 三处一致
+  返回 `false`。⇒ 这些边框**从来没有被渲染过**；而配套的
+  `border-left-color` 只是给一条 0 宽、style 为 none 的边上色 ⇒ 全线不可见。
+- 为什么别的门禁抓不到：它不影响解析、不抛异常、不改变任何可断言的行为，
+  只是**观感**缺了一块；而观感只有视觉回归能验。
+- 门禁：`css-validity`（判据交给浏览器自己，不手写属性白名单 ——
+  手写的那份是第二份真相源，见 I-7）。
+
+### I-13 `npm install file:` 不做打包，会连未发布目录一起软链进来
+
+- 实证：一度以为 `npm pack` 泄漏内部文档。实测证伪——真实 `npm pack` + 安装是干净的。
+- 教训：**用真实 tarball 安装验证，不要用 `file:` 的假象下结论。**
+- 门禁：`pack-smoke.sh`。
+
+### I-14 同一语义的样式若在每个使用点各写一份，"改一处"在物理上不成立
+
+- 实证：一次成套多页制作中，想改一处"全局"的东西，整批页面立刻崩。
+  机械测量（39 个使用点）：页面框、内容列、标题阶梯、行内代码、说明块
+  这几样"全局"的东西，各自出现在 21–36 个使用点、同一个选择器有 7–16 种写法，
+  其中若干**已经存在共享定义**，使用点仍在重抄。
+- 反方向的机械证据：把改动之前的版本取出，用同一把尺子量
+  "改一个全局变量，这个使用点跟不跟着变" ⇒ 36 处不跟随。
+- 推论：**"全局可改"不是写法问题，而是"存在唯一汇聚点"这一事实的结果。**
+  没有汇聚点，改动的完整性就只能靠逐点同步，而逐点同步必然漏。
+- 推论二：一个已被收编的选择器若在使用点仍被书写，会被更高特异性的定义
+  **静默盖掉**，成为死声明 —— 不报错、不影响解析，只在"改了却没变"时才暴露。
+- 门禁：`shell`（禁止使用点重抄骨架）+ `skel-lever`（在真实浏览器里要求
+  每一个使用点都跟随同一全局变量的改动，并含"不引骨架的使用点不得被影响"的反向控制）。
+
+### I-15 判据绑在**内容**上才稳定；绑在**字节**或**位置**上必然自相矛盾
+
+同一份内容在两个环境下给出两个结论 ⇒ 判据一定绑错了东西。
+这类缺陷不表现为"检查失灵"，而表现为"换个环境结论就变"，
+因此极难复现：维护者本地永远绿，只有陌生人一上来就撞上。
+
+- 实证 A（绑在字节上）：新鲜度判据按磁盘字节算散列。
+  源码在提交库里换行符是混合状态（实测 LF 17 个、CRLF 32 个）；
+  别人克隆后，签出时的换行符自动转换把那 17 个改成 CRLF
+  ⇒ 内容一字未改，17 个文件全部被判"产物不新鲜"。
+  ⇒ 修法：散列先把 CRLF 归一成 LF 再算（产物本就是按文本读的，不含 CR），
+    并把"只换换行符仍然绿"写成常驻自检。
+- 实证 B（绑在位置上）：产物目录里的文件与它的源码同源同内容，
+  但两道门禁的例外/豁免是按路径前缀判的 ⇒ 源码侧放行、产物侧报错。
+  同一份内容，两个相反结论 —— 错的不是产物，是判据把规则写在了位置而不是内容上。
+  ⇒ 修法：判例前先把产物路径映射回源路径，规则只写一份。
+- 推论：**凡出现"内容相同却判定不同"，先怀疑判据绑错了东西，而不是改内容去凑判据。**
+  后者会把门禁逼成一个说谎的尺子。
+
+---
+
+## 五、这一层**不**包含什么
+
+明确排除，避免这一层被污染后失去"永不变"的性质：
+
+| 不写在这里 | 应该去哪 | 理由 |
+|---|---|---|
+| "改之前先跑 impact-report.py" | `GUIDANCE.md` | 这是工作建议。更强的模型自己就能判断影响面 |
+| "AI 应该先读 README" | `GUIDANCE.md` | 同上 |
+| "本版有 N 个组件"（**写具体数字**的那种） | `ai/components.json`（Contract） | 会随版本变 |
+| "某档位只允许某成熟度的组件" | `ai/profiles.json`（Contract） | 这是**约定**，不是事实，可以改 |
+| "不要写 magic number" | `GUIDANCE.md` | 这是品味建议，不是物理事实 |
+
+---
+
+## 六、怎么保证这一层不被污染
+
+`05-audit/invariant-gate.py` 会检查：
+
+1. 本文件中**不出现**任何组件名、令牌名、版本号、档位名（出现 ⇒ 那是 Contract 的内容）
+2. 本文件中**不出现** "应该 / 建议 / 推荐 / 最好" 这类措辞（出现 ⇒ 那是 Guidance 的内容）
+3. `ai/contract.schema.json` 里声明的 `invariants` 条目，与本文件的锚点**一一对应**
+
+⇒ 门禁先于人情。想往这层塞东西，得先说服门禁。

package/docs/LAYER-BASELINE.md

@@ -0,0 +1,158 @@
+# `@layer` 的 WebView 基线（W12）
+
+> **当前状态：部分验证（7 行），且已出现 1 个阻塞样本。**
+> 已有 7 行真机实测。**`@layer` 6 行通过、1 行不通过**：
+>
+> | 入口 | 结果 |
+> |---|---|
+> | iOS 18.7 · Safari | 15 / 15 |
+> | Android 14 · 微信 8.0.47（XWEB / Chromium 146） | 14 / 15，缺 `scrollbar-width`（有私有回退） |
+> | iOS 26.6.2 · 微信 8.0.79（WKWebView） | 15 / 15 |
+> | iOS 18.7 · 企业微信 5.0.12（wxwork） | 15 / 15 |
+> | iPad · Safari 26.6.1（桌面版 UA） | 15 / 15 |
+> | iPhone · QQ 浏览器 20.6.6 | 15 / 15 |
+> | **Android 14 · 百度浏览器 13.51（Chromium 97）** | **11 / 15，缺 `@layer`** 🔴 |
+>
+> ⚠️ **百度浏览器那一行是决定性的**：它证明"国产 App 内置浏览器长期停在老内核"
+> 不是猜测 —— Chromium 97（2022 年初）不认识 `@layer`，切层后**那一层样式会整段消失**。
+>
+> 按下面第三节的判据：**已有一行 `@layer` 不通过 ⇒ 当前不能无条件切层**，
+> 只能走 `@supports at-rule(@layer)` 双写，或者不切。
+
+---
+
+## 〇、数据是怎么来的
+
+不是手抄的，也不是推测的：探针页把结果 **POST 回采集端**，落成 JSON 后原样贴进表格。
+手机访问 `http://<电脑内网地址>:端口` 属于**非安全上下文**，
+`navigator.clipboard` 在那里根本不存在 —— 所以页面提供的是"发送到电脑"（同源 POST）作为主路径，
+剪贴板只作备用（详见 `ERRORS.md` E47）。
+
+---
+
+## 一、为什么切 `@layer` 之前必须先有这个基线
+
+`@layer` 与其它 CSS 特性有一个**性质上的区别**：
+
+| 特性 | 不支持时的表现 |
+|---|---|
+| `:has()` / `clamp()` / `dvh` / `aspect-ratio` | **单条声明或单条规则失效** —— 局部退化，页面还能看 |
+| `@layer` | 引擎不认识 `@layer { … }` 这个**块**，整块规则被当作非法内容丢弃 —— **整段样式消失** |
+
+⇒ 不支持 `@layer` 的引擎上，不是"层叠顺序不对"，而是"**这一层里的所有样式都没了**"。
+`cascade-layer-gate.py` 现在只证明"我们**有能力**切层"（`!important` 都能归类、层数可控），
+它证明不了"切完之后**目标浏览器**还认识它"。
+
+⇒ 基线就是这个"目标浏览器认识不认识"的证据。没有它，切层是一次**没有安全网的改动**。
+
+---
+
+## 二、怎么测（三条路径，任选一条）
+
+探针页：`10-review/webview/capability-probe.html`
+（自包含单文件：不引本库 CSS、不引外部资源，拷到手机上直接能开）
+
+1. **局域网**（最省事）
+   在仓库根目录起静态服务（`npx serve` / `python -m http.server`），
+   手机与电脑连同一个无线局域网，访问 `http://<电脑内网地址>:<端口>/10-review/webview/capability-probe.html`
+2. **拷文件**
+   把这个 HTML 单独发到手机（文件传输 / 数据线），用系统浏览器或目标 App 的 WebView 打开
+3. **云真机**
+   需要覆盖 iOS WKWebView 与 Android System WebView 两类内核时用
+
+页面会输出一段 JSON（点「复制结果」按钮）⇒ 整段贴进下面表格的「结果」列即可。
+
+⚠️ 一定要说明**从哪个入口打开的**：
+Safari 里打开 ≠ WKWebView 里打开（同一内核，但 `WebKit` 的宿主配置会关掉部分能力），
+Android 上 Chrome ≠ 系统 WebView ≠ 各家 App 内置 WebView。**入口写不清楚，数据就没法用。**
+
+---
+
+## 三、判据：什么时候才有资格切层
+
+🔴 **先把两类缺失分开**（这一点是被真机数据纠正的）：
+`@layer` 能不能用，与"某一项别的能力缺失"是**两件事**。
+第一版判据把两者混在一起，于是微信缺一个 `scrollbar-width` 就会被判成"不能切层" ——
+而那个缺失跟层叠毫无关系，且本库有私有回退。
+
+| 类别 | 判据 | 动作 |
+|---|---|---|
+| **阻塞切层** | 任一行 `@layer` 实测**不通过** | 只能走 `@supports at-rule(@layer)` 双写，或者不切 |
+| **不阻塞切层** | 除 `@layer` 外的其它能力缺失 | 不影响层叠决策；但必须逐条判定"有没有回退、降级后是否可接受"，并把结论写进「缺失能力」列 |
+| **可以无条件切** | 目标受众内**每一行** `@layer` 都通过 | 直接切 |
+
+⚠️ "每一行"是**字面意思**：目标受众里还有一台设备不过，就不能无条件切。
+`docs/INVARIANT.md` 的口径是"约束要么成立、要么被写进合同"，不存在"大部分成立"。
+
+**当前判定：不能无条件切层。**
+5 行里 **百度浏览器（Chromium 97）不支持 `@layer`** —— 而 `@layer` 不支持时，
+**整层规则会被丢弃**（不是"层序不对"，是"那一层的样式没了"）。
+⇒ 要么 `@supports at-rule(@layer)` 双写，要么不切。
+
+⚠️ 决策还差一步：**百度浏览器在本库的目标受众里占多少**。
+这一条数据只能回答"支不支持"，回答不了"值不值得为它放弃切层" ——
+那是产品判断，不该由基线表替使用者下结论。
+
+| 已有 | 缺 |
+|---|---|
+| iPhone Safari、iPad Safari、iPad 微信、iPad 企微、iPhone QQ 浏览器、Android 微信（XWEB）、Android 百度浏览器（Chromium 97） | Android 系统 WebView（Chrome）、其它 App 内置内核（抖音 / 小红书 / 支付宝…） |
+
+另有一条**方法论**上的收获，值得单独记下来：
+
+> `scrollbar-width` 在微信 XWEB 里 `CSS.supports` 返回 `false`，
+> 但本库的滚动条样式**照样生效** —— 因为 `01-tokens/scrollbar.css` 同时写了
+> `::-webkit-scrollbar` 私有实现。
+> ⇒ **「探针说这一项不支持」不等于「这个能力在本库里没有效果」。**
+> 判读基线表时必须回到源码看一眼有没有第二条路，否则会把"可接受降级"误判成"缺陷"。
+
+---
+
+## 四、记录表
+
+<!--
+  填写规则（门禁 webview-probe-gate.py 会核对）：
+  · 每一行 8 列都必须填，不许留 `?` / `TBD` / `待填` / `TODO`
+  · 「状态」只能是 `UNVERIFIED` 或 `VERIFIED`
+  · 标成 `VERIFIED` 的行，UA 必须是**从页面 JSON 里复制出来的完整 UA**（不是"iPhone 15"这种简称）
+  · 「结果」列写 `支持 N / 15`，缺失项写在「缺失能力」列
+  当前 7 行（iPhone Safari / iPad 微信 / iPad 企微 / iPad Safari / iPhone QQ 浏览器 / Android 微信 XWEB / Android 百度浏览器）。**Android 系统 WebView 仍没有 —— 那是缺口，不是"没问题"。**
+  「测试日期」不写死年月日：这个文件在公开仓里，写死日期等于把内部时间线留在仓库里
+  （`leak-scan` 的「工作日期戳」判据就是为了这个）。日期以**提交时间**为准，精确到秒且无法伪造。
+  「UA」里凡是**身份标识**（如微信的 `MMWEBID`）一律脱敏成 `<已脱敏>` ——
+  基线需要的是技术信息（内核与版本），不是谁测的。
+-->
+
+| 设备 / 系统 | 入口 | UA | 结果 | 缺失能力 | 测试日期 | 记录人 | 状态 |
+|---|---|---|---|---|---|---|---|
+| iPhone · Safari（UA 自述；430×932 是 iPhone 15/16 Pro Max 逻辑尺寸） | Safari（系统浏览器） | `Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6.1 Mobile/15E148 Safari/604.1` | 15 / 15 | 无 | 见采集所在提交（git log） | 项目所有者（真机） | VERIFIED |
+| Android 14（视口 400×787 @2.7x） | 微信 8.0.47 内置 WebView（XWEB 内核，Chromium 146） | `Mozilla/5.0 (Linux; Android 14; PHZ110 Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/146.0.7680.178 Mobile Safari/537.36 XWEB/1460249 MMWEBSDK/20231202 MMWEBID/<已脱敏> MicroMessenger/8.0.47.2560 WeChat/arm64 Weixin NetType/WIFI Language/zh_CN ABI/arm64` | 14 / 15 | `scrollbar-width` —— **标准 API 缺失，但本库有私有回退**：`01-tokens/scrollbar.css` 同时写了 `::-webkit-scrollbar` 伪元素族，XWEB 是 Chromium 内核，私有实现仍在 ⇒ 观感可接受降级，不是缺陷 | 见采集所在提交（git log） | 项目所有者（真机） | VERIFIED |
+| iPad · 微信（**用户口述为平板**；UA 与视口均为 iPhone ⇒ iPad 上以 iPhone 兼容模式运行） | 微信 8.0.79 内置 WebView（WKWebView） | `Mozilla/5.0 (iPhone; CPU iPhone OS 26_6_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 MicroMessenger/8.0.79(0x18004f2b) NetType/WIFI Language/zh_CN` | 15 / 15 | 无 | 见采集所在提交（git log） | 项目所有者（真机） | VERIFIED |
+| iPad · 企业微信（**用户口述为平板**；UA 与视口均为 iPhone ⇒ 兼容模式运行） | 企业微信 5.0.12 内置 WebView（wxwork） | `Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko)  Mobile/15E148 wxwork/5.0.12 MicroMessenger/7.0.1 Language/zh ColorScheme/Light wwmver/3.26.511.377` | 15 / 15 | 无 | 见采集所在提交（git log） | 项目所有者（真机） | VERIFIED |
+| Android 14（视口 360×672 @3x） | 百度浏览器 13.51（baiduboxapp，Chromium 97 内核） | `Mozilla/5.0 (Linux; Android 14; PHZ110 Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/97.0.4692.98 Mobile Safari/537.36 T7/13.51 SP-engine/2.89.0 baiduboxapp/13.51.0.10 (Baidu; P1 14) NABar/1.0` | 11 / 15 | 🔴 **`@layer` —— 阻塞项**：Chromium 97 太老，分层不可用 ⇒ **不能无条件切层**。另缺三项，均非阻塞：`dvh`（`page.css` 先写 `100vh` 再写 `100dvh`，老内核丢后者留前者）；`scrollbar-width`（有 `::-webkit-scrollbar` 私有回退）；原生 Popover 属性（**本库未使用**，只有自研类名 `.popover`，与本库无关） | 见采集所在提交（git log） | 项目所有者（真机） | VERIFIED |
+| iPad · Safari（**用户口述为平板**；UA 是桌面版 = iPad 请求桌面网站，视口 834×1210 与 iPad Pro 11" 一致） | Safari 26.6.1（桌面版 UA） | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.6.1 Safari/605.1.15` | 15 / 15 | 无 | 见采集所在提交（git log） | 项目所有者（真机） | VERIFIED |
+| iPhone · QQ 浏览器（**用户口述为手机**；视口 430×736 @3x） | QQ 浏览器 20.6.6（MQQBrowser，WKWebView） | `Mozilla/5.0 (iPhone; CPU iPhone OS 26_6_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 MQQBrowser/20.6.6 Mobile/15E148 Safari/604.1 QBWebViewUA/2 QBWebViewType/1 WKType/1` | 15 / 15 | 无 | 见采集所在提交（git log） | 项目所有者（真机） | VERIFIED |
+
+---
+
+## 五、刻意不写的东西
+
+**本文件不写任何引擎版本号。**
+
+「iOS 16.4 才支持某个特性」这类说法在本文件里没有位置，原因很直接：
+我没有在真机上验证过它，写下来就会被下一个人当成事实引用
+（`ERRORS.md` E13 记过一类同源事故：文档里的结论没人回来复核，最后整份文档都在骗人）。
+
+⇒ 需要版本结论时，**跑一次探针页**，用那一次的 UA 与结果说话。
+UA 是证据，版本传闻不是。
+
+---
+
+## 六、与 `10-review/ios/` 的分工
+
+| 文件 | 回答什么 | 谁来填 |
+|---|---|---|
+| `10-review/ios/index.html` | **观感与交互**在 Safari 下对不对（按钮、键盘弹起、暗色） | 人眼看，逐条对 |
+| `10-review/webview/capability-probe.html` | **能力**在目标 WebView 里有没有（`@layer` 等 15 项） | 机器判定，人只负责贴 JSON |
+
+两者不能互相替代：能力全支持而观感崩了，和观感正常但 `@layer` 被整段丢弃，
+是两种完全不同的事故。