agentcss 0.24.1 → 0.25.0

package/dist/09-assets/echarts-adapter/echarts-adapter.js

@@ -1,26 +1,34 @@
 (function () {
 'use strict';
 
-function cssVar(name, fallback) {
+function cssVar(name, fallback, ctx) {
 if (typeof window.getComputedStyle !== 'function') return fallback;
-var v = getComputedStyle(document.documentElement).getPropertyValue(name);
+var el = ctx || document.documentElement;
+var v = getComputedStyle(el).getPropertyValue(name);
 return (v && v.trim()) || fallback;
 }
 
-function palette() {
+function scopeOf(el) {
+try {
+if (el && el.closest) return el.closest('[data-theme]') || document.documentElement;
+} catch (e) {  }
+return document.documentElement;
+}
+
+function palette(ctx) {
 return {
-text: cssVar('--text-primary', '#15181c'),
-textSub: cssVar('--text-secondary', '#5b6472'),
-textTertiary: cssVar('--text-tertiary', '#8a94a3'),
-surface: cssVar('--surface', '#ffffff'),
-paper: cssVar('--paper', '#f6f7f8'),
-border: cssVar('--border-decor', '#e2e5e9'),
-borderStrong: cssVar('--border-control', '#868b94'),
-danger: cssVar('--danger', '#c0392b'),
-success: cssVar('--success', '#2e7d52'),
-warn: cssVar('--warning', '#b8860b'),
-info: cssVar('--info', '#2b7a9e'),
-accent: cssVar('--accent', '#1b4d8f'),
+text: cssVar('--text-primary', '#15181c', ctx),
+textSub: cssVar('--text-secondary', '#5b6472', ctx),
+textTertiary: cssVar('--text-tertiary', '#8a94a3', ctx),
+surface: cssVar('--surface', '#ffffff', ctx),
+paper: cssVar('--paper', '#f6f7f8', ctx),
+border: cssVar('--border-decor', '#e2e5e9', ctx),
+borderStrong: cssVar('--border-control', '#868b94', ctx),
+danger: cssVar('--danger', '#c0392b', ctx),
+success: cssVar('--success', '#2e7d52', ctx),
+warn: cssVar('--warning', '#b8860b', ctx),
+info: cssVar('--info', '#2b7a9e', ctx),
+accent: cssVar('--accent', '#1b4d8f', ctx),
 };
 }
 
@@ -30,17 +38,47 @@ if (n > ramp.length) return null;
 return ramp.slice(0, n);
 }
 
-function theme(name, p) {
-p = p || palette();
-var isDark = document.documentElement.getAttribute('data-theme-current') === 'dark'
-|| cssVar('--paper', '#fff') !== '#f6f7f8';
+function parseColor(v) {
+if (!v) return null;
+var t = String(v).trim();
+var m = /^#([0-9a-f]{3})$/i.exec(t);
+if (m) {
+return [parseInt(m[1][0] + m[1][0], 16),
+parseInt(m[1][1] + m[1][1], 16),
+parseInt(m[1][2] + m[1][2], 16)];
+}
+m = /^#([0-9a-f]{6})$/i.exec(t);
+if (m) {
+return [parseInt(m[1].slice(0, 2), 16),
+parseInt(m[1].slice(2, 4), 16),
+parseInt(m[1].slice(4, 6), 16)];
+}
+m = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/i.exec(t);
+if (m) return [Math.round(+m[1]), Math.round(+m[2]), Math.round(+m[3])];
+return null;
+}
+
+function isDarkScope(ctx) {
+var c = parseColor(cssVar('--paper', '', ctx));
+if (!c) return false;
+var lin = c.map(function (v) {
+v = v / 255;
+return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+});
+
+return (0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]) < 0.18;
+}
+
+function theme(name, p, ctx) {
+p = p || palette(ctx);
+var isDark = isDarkScope(ctx);
 
 return {
 color: [p.accent, p.danger, p.success, p.warn, p.info],
 backgroundColor: 'transparent',
 textStyle: {
 color: p.text,
-fontFamily: cssVar('--sans', 'system-ui, sans-serif'),
+fontFamily: cssVar('--sans', 'system-ui, sans-serif', ctx),
 },
 title: {
 textStyle: { color: p.text, fontWeight: 600 },
@@ -48,7 +86,8 @@ subtextStyle: { color: p.textSub },
 },
 legend: { textStyle: { color: p.textSub } },
 tooltip: {
-backgroundColor: isDark ? '#1c2024' : '#ffffff',
+
+backgroundColor: cssVar('--surface', isDark ? '#1c2024' : '#ffffff', ctx),
 borderColor: p.border,
 borderWidth: 1,
 textStyle: { color: p.text, fontSize: 12 },
@@ -75,12 +114,12 @@ splitNumber: 4,
 };
 }
 
-function defaults(option) {
-var p = palette();
+function defaults(option, ctx) {
+var p = palette(ctx);
 var o = option || {};
 
 o.textStyle = merge(o.textStyle, {
-fontFamily: cssVar('--mono', 'ui-monospace, monospace'),
+fontFamily: cssVar('--mono', 'ui-monospace, monospace', ctx),
 });
 
 o.grid = merge(o.grid, { left: 56, right: 24, top: 32, bottom: 32, containLabel: false });
@@ -124,9 +163,8 @@ console.warn('[frontend-lib] 系列数 ' + o.series.length +
 return o;
 }
 
-function currentThemeName() {
-return 'fe-' +
-(document.documentElement.getAttribute('data-theme-current') || 'light');
+function currentThemeName(ctx) {
+return 'fe-' + (isDarkScope(ctx) ? 'dark' : 'light');
 }
 
 function create(dom, opt) {
@@ -137,16 +175,17 @@ console.warn('[frontend-lib] 未检测到 ECharts —— ' +
 }
 return null;
 }
-var name = currentThemeName();
+var ctx = scopeOf(dom);
+var name = currentThemeName(ctx);
 
 if (typeof window.echarts.registerTheme === 'function') {
-window.echarts.registerTheme(name, theme(name));
+window.echarts.registerTheme(name, theme(name, null, ctx));
 }
 var inst = window.echarts.init(dom, name);
 inst.__feDom = dom;
 inst.__feOpts = opt || {};
 inst.__feTheme = name;
-inst.setOption(defaults(inst.__feOpts));
+inst.setOption(defaults(inst.__feOpts, ctx));
 return inst;
 }
 
@@ -162,14 +201,17 @@ cssVar: cssVar,
 palette: palette,
 seriesColors: seriesColors,
 theme: theme,
+
+themeName: currentThemeName,
 defaults: defaults,
 create: create,
 
 refresh: function (inst) {
 if (!inst) return;
-var name = currentThemeName();
+var ctx = scopeOf(inst.__feDom);
+var name = currentThemeName(ctx);
 if (typeof window.echarts !== 'undefined' && window.echarts.registerTheme) {
-window.echarts.registerTheme(name, theme(name));
+window.echarts.registerTheme(name, theme(name, null, ctx));
 }
 
 if (inst.__feDom) {
@@ -177,7 +219,7 @@ var opt = inst.__feOpts;
 inst.dispose();
 return create(inst.__feDom, opt);
 }
-inst.setOption(defaults(inst.__feOpts), name);
+inst.setOption(defaults(inst.__feOpts, ctx), name);
 return inst;
 },
 };

package/dist/09-assets/scientific-plot/scientific-plot.js

@@ -25,13 +25,6 @@ return String(s == null ? '' : s)
     return v.toFixed(p);
   }
 
-  function cssVar(name, fallback) {
-    if (typeof getComputedStyle !== 'function' || !document.documentElement) return fallback;
-    var v = getComputedStyle(document.documentElement).getPropertyValue(name);
-    v = v ? v.trim() : '';
-    return v || fallback;
-  }
-
   /* --------------------------------------------------------------- 比例尺 */
 
   /**

package/dist/COSTS.md

@@ -9,52 +9,52 @@
 
 实测两笔账，一笔不省：
 
-- `tokens` 源码版 gzip **20.4 KB** → min 版 **2.7 KB**（省 87%）——
-  源码多的那部分**全是注释**（全库 CSS 有 68% 是注释，字节口径），而注释是给维护者的，不是给浏览器的。
-- tokens 的 min 版 2.7 KB **比任何一个组件自己都贵** ⇒
+- `tokens` 源码版 gzip **21.9 KB** → min 版 **2.9 KB**（省 87%）——
+  源码多的那部分**全是注释**（全库 CSS 有 69% 是注释，字节口径），而注释是给维护者的，不是给浏览器的。
+- tokens 的 min 版 2.9 KB **比任何一个组件自己都贵** ⇒
   "只用一个组件"的真实起步价就是它。不公开这张表，等于让人盲买。
 
 ## 二、明码标价
 
 | 档 | 组件 | tokens（必付） | CSS | JS | **合计** | 源码版合计 | 差 |
 |---|---|---:|---:|---:|---:|---:|---:|
-| primitive | `badge` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 23.1 KB | −19.9 KB |
-| primitive | `button` | 2.7 KB | 1.0 KB | — | **3.7 KB** | 26.8 KB | −23.1 KB |
-| primitive | `card` | 2.7 KB | 0.9 KB | — | **3.7 KB** | 24.5 KB | −20.8 KB |
-| primitive | `choice` | 2.7 KB | 1.1 KB | — | **3.8 KB** | 26.3 KB | −22.5 KB |
-| primitive | `combobox` | 2.7 KB | 1.0 KB | 5.4 KB | **9.1 KB** | 29.9 KB | −20.9 KB |
-| primitive | `date-range` | 2.7 KB | 0.8 KB | 2.5 KB | **6.1 KB** | 26.9 KB | −20.8 KB |
-| primitive | `delta` | 2.7 KB | 0.3 KB | — | **3.0 KB** | 23.1 KB | −20.2 KB |
-| primitive | `input` | 2.7 KB | 1.0 KB | — | **3.8 KB** | 24.3 KB | −20.6 KB |
-| primitive | `metric` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 23.6 KB | −20.4 KB |
-| primitive | `popover` | 2.7 KB | 0.8 KB | 2.2 KB | **5.7 KB** | 27.7 KB | −22.0 KB |
-| primitive | `progress` | 2.7 KB | 0.8 KB | — | **3.5 KB** | 24.7 KB | −21.2 KB |
-| primitive | `select` | 2.7 KB | 0.8 KB | 3.5 KB | **7.1 KB** | 30.0 KB | −22.9 KB |
-| primitive | `separator` | 2.7 KB | 0.2 KB | — | **3.0 KB** | 21.7 KB | −18.7 KB |
-| primitive | `skeleton` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 22.3 KB | −19.1 KB |
-| primitive | `switch` | 2.7 KB | 0.8 KB | — | **3.5 KB** | 28.7 KB | −25.2 KB |
-| primitive | `timeline` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 23.7 KB | −20.4 KB |
-| primitive | `upload` | 2.7 KB | 1.4 KB | 4.2 KB | **8.3 KB** | 37.8 KB | −29.5 KB |
-| pattern | `accordion` | 2.7 KB | 1.3 KB | 1.8 KB | **5.8 KB** | 34.9 KB | −29.1 KB |
-| pattern | `content` | 2.7 KB | 1.0 KB | — | **3.7 KB** | 25.0 KB | −21.2 KB |
-| pattern | `drawer` | 2.7 KB | 0.8 KB | 2.5 KB | **6.0 KB** | 27.5 KB | −21.5 KB |
-| pattern | `dropdown` | 2.7 KB | 0.8 KB | 3.4 KB | **6.9 KB** | 29.8 KB | −22.9 KB |
-| pattern | `form-validation` | 2.7 KB | 0.8 KB | — | **3.5 KB** | 24.9 KB | −21.4 KB |
-| pattern | `list` | 2.7 KB | 0.6 KB | — | **3.3 KB** | 22.8 KB | −19.5 KB |
-| pattern | `nav` | 2.7 KB | 1.2 KB | 2.6 KB | **6.6 KB** | 31.5 KB | −24.9 KB |
-| pattern | `overlay` | 2.7 KB | 1.1 KB | 3.3 KB | **7.1 KB** | 35.3 KB | −28.1 KB |
-| pattern | `pagination` | 2.7 KB | 0.8 KB | 2.6 KB | **6.1 KB** | 30.9 KB | −24.9 KB |
-| pattern | `reveal` | 2.7 KB | 0.3 KB | 1.2 KB | **4.2 KB** | 24.9 KB | −20.7 KB |
-| pattern | `states` | 2.7 KB | 0.8 KB | — | **3.6 KB** | 24.4 KB | −20.9 KB |
-| pattern | `tabs` | 2.7 KB | 0.7 KB | 2.0 KB | **5.4 KB** | 27.6 KB | −22.2 KB |
-| pattern | `tooltip` | 2.7 KB | 0.5 KB | 1.9 KB | **5.1 KB** | 26.8 KB | −21.7 KB |
-| pattern | `tree` | 2.7 KB | 0.6 KB | 2.9 KB | **6.3 KB** | 28.6 KB | −22.3 KB |
+| primitive | `badge` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 24.6 KB | −21.2 KB |
+| primitive | `button` | 2.9 KB | 1.0 KB | — | **3.9 KB** | 28.3 KB | −24.4 KB |
+| primitive | `card` | 2.9 KB | 0.9 KB | — | **3.9 KB** | 26.0 KB | −22.1 KB |
+| primitive | `choice` | 2.9 KB | 1.1 KB | — | **4.0 KB** | 27.8 KB | −23.8 KB |
+| primitive | `combobox` | 2.9 KB | 1.0 KB | 5.4 KB | **9.3 KB** | 31.4 KB | −22.1 KB |
+| primitive | `date-range` | 2.9 KB | 0.8 KB | 2.5 KB | **6.3 KB** | 28.4 KB | −22.1 KB |
+| primitive | `delta` | 2.9 KB | 0.3 KB | — | **3.2 KB** | 24.6 KB | −21.4 KB |
+| primitive | `input` | 2.9 KB | 1.0 KB | — | **4.0 KB** | 25.8 KB | −21.9 KB |
+| primitive | `metric` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 25.1 KB | −21.7 KB |
+| primitive | `popover` | 2.9 KB | 0.8 KB | 2.2 KB | **5.9 KB** | 29.2 KB | −23.3 KB |
+| primitive | `progress` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 26.2 KB | −22.5 KB |
+| primitive | `select` | 2.9 KB | 0.8 KB | 4.1 KB | **7.9 KB** | 32.9 KB | −24.9 KB |
+| primitive | `separator` | 2.9 KB | 0.2 KB | — | **3.2 KB** | 23.2 KB | −20.0 KB |
+| primitive | `skeleton` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 23.8 KB | −20.4 KB |
+| primitive | `switch` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 30.2 KB | −26.5 KB |
+| primitive | `timeline` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 25.1 KB | −21.7 KB |
+| primitive | `upload` | 2.9 KB | 1.4 KB | 4.2 KB | **8.5 KB** | 39.3 KB | −30.8 KB |
+| pattern | `accordion` | 2.9 KB | 1.3 KB | 1.8 KB | **6.0 KB** | 36.4 KB | −30.4 KB |
+| pattern | `content` | 2.9 KB | 1.0 KB | — | **4.0 KB** | 26.5 KB | −22.5 KB |
+| pattern | `drawer` | 2.9 KB | 0.8 KB | 2.5 KB | **6.2 KB** | 29.0 KB | −22.8 KB |
+| pattern | `dropdown` | 2.9 KB | 0.8 KB | 3.4 KB | **7.1 KB** | 31.3 KB | −24.2 KB |
+| pattern | `form-validation` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 26.8 KB | −23.1 KB |
+| pattern | `list` | 2.9 KB | 0.6 KB | — | **3.5 KB** | 24.3 KB | −20.8 KB |
+| pattern | `nav` | 2.9 KB | 1.2 KB | 2.6 KB | **6.8 KB** | 33.0 KB | −26.2 KB |
+| pattern | `overlay` | 2.9 KB | 1.2 KB | 3.5 KB | **7.6 KB** | 38.1 KB | −30.5 KB |
+| pattern | `pagination` | 2.9 KB | 0.8 KB | 2.6 KB | **6.3 KB** | 32.4 KB | −26.1 KB |
+| pattern | `reveal` | 2.9 KB | 0.3 KB | 1.2 KB | **4.4 KB** | 26.4 KB | −22.0 KB |
+| pattern | `states` | 2.9 KB | 0.9 KB | — | **3.8 KB** | 26.3 KB | −22.5 KB |
+| pattern | `tabs` | 2.9 KB | 0.7 KB | 2.0 KB | **5.6 KB** | 29.1 KB | −23.5 KB |
+| pattern | `tooltip` | 2.9 KB | 0.5 KB | 1.9 KB | **5.3 KB** | 28.3 KB | −23.0 KB |
+| pattern | `tree` | 2.9 KB | 0.6 KB | 2.9 KB | **6.5 KB** | 30.1 KB | −23.6 KB |
 
 ## 三、全库
 
-- 全部组件都用上（min，含 tokens 一份）：**69.0 KB**
-- 源码版（带注释）全库 gzip：349.2 KB
+- 全部组件都用上（min，含 tokens 一份）：**70.2 KB**
+- 源码版（带注释）全库 gzip：356.4 KB
 
-> ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 68% 是注释，字节口径）。
+> ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 69% 是注释，字节口径）。
 > 它的用途只有一个 —— 让人看清"dist 到底省了多少"。
 

package/docs/ACCESSIBILITY.md

@@ -5,8 +5,8 @@
 
 | 项目 | 值 |
 |---|---|
-| 声明适用版本 | agentcss `0.24.1` |
-| 声明日期 | 2026-10-31 |
+| 声明适用版本 | agentcss `0.25.0` |
+| 声明日期 | 2026-11-02 |
 | 复核节奏 | 每次发版前重跑（`npm run gate` 内含全部证据） |
 | 范围 | 本库交付的 CSS / JS、全部 `demo.html`（组件页 + 图表页 + 组合页）、以及文档站生成的页面 |
 | 不在范围 | 使用者拿这些组件拼出来的业务页面（那是你的无障碍责任，不是库的） |
@@ -85,7 +85,7 @@
 | `heading-outline.js`（人工工具） | **全部 HTML：96 页 / 887 个标题** | 0 处跳级 · 每页恰好 1 个 `h1` · DOM 标题数 == 无障碍树 heading 数 |
 | `a11y-ax.js` 可访问性树 | **全部 `demo.html`（现 40 个）**；清单与磁盘不一致即红 | 0 个无名控件；40 份朗读序列快照在 `10-review/a11y-tree/` |
 | `contrast.py` / `dark-contrast.js` | 亮 / 暗两套，逐对实算 | 正文 ≥ 4.5:1 |
-| `zoom-reflow.js` | 40 页 × 3 条 AA 硬项 | 320px 不横滚 · 200% 不裁字 · 焦点不被遮挡 |
+| `zoom-reflow.js` | 43 页（40 个组件 demo + 3 个文档页）× 3 条 AA 硬项；每页 1 次加载，改视口 / 字号后等**关键布局指标**稳定（指纹连续 3 帧不变，超时判红；证不到的边界见脚本头） | 320px 不横滚 · 200% 不裁字 · 焦点不被遮挡 |
 | `focus-ring-check` / `focus-return-check` / `keyboard-nav` | 焦点可见、焦点归还、键盘路径 | 全绿 |
 
 ### 人工（**已执行一轮，仍缺人耳与第二平台**）

package/docs/FACTS.md

@@ -0,0 +1,144 @@
+# 事实来源清单
+
+> **这份文档登记"事实从哪来、谁在核"，不登记"事实是多少"。**
+> 数值只存在于一个地方：`05-audit/facts.json`（生成物）。
+> 文档、README、`llms*.txt`、页面里出现的数字，全部由 `05-audit/facts-gate.py` 对着它核。
+
+---
+
+## 为什么需要这份清单
+
+同一个数字在仓库里有多个"手抄本"，一定会漂。已经真实发生过五次：
+
+| 时间 | 现象 | 根因 |
+|---|---|---|
+| 0.24.1 | `llms-full.txt` 第 13 行写 `# 39 components`，第 118 行写 `Components (40)` | 生成器里那行是**写死的字符串**，标题用的是 `len()` |
+| 0.24.1 | `AGENTS.md` 第 3 行写 `39 components` | 手写文件，没有任何判据看着它 |
+| 0.24.1 | 讨论文档写 pitfalls `19 + 12 = 31` | 实际 20 + 12 = 32，手抄 |
+| 0.24.1 | `README.zh-CN.md` 写 `共 **37** 个（stable 37 …）` | 加粗写法让老正则失配；同文件另一处 `40 个组件` 是对的，于是"找到了数"就放行 |
+| 0.24.1 | 两份 README 的组件表都只有 **37 行**，标题却写着 40 / 17 | 加组件时改了数字、没补表；中文那份连数字都没改 |
+| 更早 | `llms.txt` 写 38 个组件，契约里 39 | 同类（`docs-site-gate` 判据②抓到） |
+
+**共同点**：数字是人抄的，而人不会在每次加组件后回头改所有地方。
+
+> 上面这张表是**历史记录**，它的数字描述的是"当时错成什么样"，不是当前值；
+> 和 CHANGELOG 一样，不在判据范围内。当前值只有一个来源：`05-audit/facts.json`。
+
+⇒ 纪律：**机器算得出来的，不许手写。手写只能写解释，不能写计数。**
+
+---
+
+## 一、事实清单（登记表）
+
+"当前结果"一栏故意只写 `facts.json` 的键路径，不写数值——写数值就等于再造一个手抄本。
+
+| # | 事实 | 唯一权威来源 | 提取方式 | 当前结果 | 对外声明形态 | 谁在核 |
+|---|---|---|---|---|---|---|
+| F1 | 组件总数 | `ai/components.json` → `components[]` | `len()` | `components.total` | **数字**：`llms.txt` ×2、`llms-full.txt` ×2、`AGENTS.md`、`index.html`、`404.html`、`guide/index.html` ×2、`README.md`、`README.zh-CN.md` ×2 | ③ |
+| F2 | 按层的组件数 | 同上 → `tier` | 分组计数 | `components.byTier` | **数字 ×2 形态**：每个分节标题里的 `（17）`，以及该分节表格的**行数**（两份 README 各 4 层） | **⑤** |
+| F3 | 按成熟度的组件数 | 同上 → `maturity` | 分组计数 | `components.byMaturity` | **数字**：`README.md` 的 `stable 40 / beta 0`、`README.zh-CN.md` 的 `stable 40` | ③ |
+| F4 | 带行为层的组件数 | 同上 → `global` 非 null | 计数 | `components.withBehaviorLayer` | 无数字声明（`README` 只写"行为层是可选的"，不报数） | — |
+| F5 | 翻车点总数（组件/布局/流程） | `ai/pitfalls.json` → `pitfalls[]` | `len()` | `pitfalls.total` | 无独立声明，只作为 F7 的加数出现 | — |
+| F6 | 写作类翻车点数 | `ai/pitfalls-writing.json` → `pitfalls[]` | `len()` | `pitfallsWriting.total` | 同上 | — |
+| F7 | 翻车点合计 | F5 + F6 | 求和 | `pitfallsAll` | **数字**：`llms-full.txt` 的 `Known failure modes (32)` | ③ |
+| F8 | 运行时依赖数 | `package.json` → `dependencies` | `len()`，且**必须为 0** | `dependencies.runtime` | **散文断言**（"Zero third-party runtime dependencies"），没有数字可核 | **① 结构判据**：出现任何 `dependencies` 即红 |
+| F9 | 开发依赖数 | `package.json` → `devDependencies` | `len()` | `dependencies.dev` | 无数字声明 | — |
+| F10 | 版本号 | `VERSION`（并与 `package.json.version` 互校） | 读文件 + 比对 | `version` | **版本戳**（不是计数）：`llms-full.txt` 头部、`docs/ACCESSIBILITY.md`、每个 `guide/*.html` 页脚 | `bump-version.py --check` + `doc-facts-gate.py`；`facts-gate` 只做 `VERSION` ↔ `package.json` 互校 |
+| F11 | CLI 子命令数 | `ai/cli.js` → `module.exports.CMDS` | `node -e` 取 `Object.keys()` | `cli.subcommands` | 无数字声明（`llms.txt` 列命令，不报个数） | — |
+
+### 1.1 三种"没有数字声明"要分清楚
+
+"这项事实没有消费者"和"这项事实没人看着"不是一回事。上表里 `—` 有三种不同含义：
+
+| 情形 | 例子 | 靠什么保证 |
+|---|---|---|
+| 有断言、但断言里没有数字 | F8 零依赖 | ① 结构判据（`dependencies` 非空即红）—— 比核数字更硬 |
+| 只有生成物在用、生成物本身派生 | F10 版本戳 | 生成器从 `VERSION` 取，天然同源；另有 `bump-version` 兜手写文档 |
+| 真的没有对外声明 | F4 / F5 / F6 / F9 / F11 | 无。**这是已知空白，不是已覆盖** |
+
+> ⚠️ 不要因为"11 项都提取了"就说"11 项都被校验了"。
+> 提取覆盖 11 项；**声明校验只覆盖 F1 / F2 / F3 / F7 四项的数字形态，外加 F8 的结构约束**。
+
+---
+
+## 二、五个环节，分别验
+
+```
+源文件 ──提取──> facts.json ──引用──> 对外声明
+   │                  │                  │
+   └─ ① 结构校验 ─────┴─ ② 现算比对 ────┴─ ③ 数字比对 + ④ 未登记扫描 + ⑤ 清单核对
+```
+
+| 判据 | 抓什么 | 在哪 |
+|---|---|---|
+| ① 源结构 | 缺字段 / 字段类型错（`null`·数字·字符串冒充数组）/ 顶层不是对象 / id 重复 / 非法 `tier`·`maturity`·`scope` / 翻车点引用不存在的组件 / `VERSION` 与 `package.json` 不一致 / 出现运行时依赖 / `files` 漏了 `ai/` | `_facts.validate_sources()` |
+| ② 现算 vs `facts.json` | "加了组件但没跑 `--write`" | `compare_facts()` |
+| ③ 声明 vs 现算 | "文档里的数写错了"（报出文件、行号、两个值） | `_facts.check_claims()` |
+| ④ 未登记扫描 | "新写了一句 `41 components`，没人管它" | 同上，`SCAN_FILES` |
+| ⑤ 清单核对 | "标题数字改了、表格没改"／"表格行数对、内容里有个不存在的组件"／"中文写着 15、英文写着 17" | `_facts.check_listings()` |
+
+**为什么 ②③④⑤ 不能合并成一条**：`docs-site-gate` 的判据 ① 是「`llms-full.txt` 逐字节等于生成器输出」——它只能证明**文件与生成器一致**，不能证明**这个数是对的**。生成器写死一个错数，两边一起错，判据照样绿。**自证式判据只能证明"一起错"。**
+
+**为什么 ③ 还要配上 ⑤**：0.24.1 的英文 README 标题写 `primitives (17)`（对）、表格只有 15 行。③ 只看那个 17，看不见表格；⑤ 数两半。反过来，中文 README 是标题 15、表格 15 行——③⑤ 都能抓 ⑤ 更准。**一条判据只能看见它量的那个东西。**
+
+---
+
+## 三、什么不算事实（明确排除）
+
+| 排除项 | 为什么 | 该去哪 |
+|---|---|---|
+| 门禁道数 | 运行时统计，随分层模式变化（`--fast` 只跑静态+视觉，`full` 跑全部），不是仓库常量 —— **本文档不写这个数** | 运行时打印 |
+| `stable` 到底保证了什么 | 是契约语义，不是一个数 | `ai/components.meta.json` 的 `maturityCriteria` + `docs/STABILITY.md` |
+| "是否经过真机验证" | 是证据状态，不是计数 | `docs/ACCESSIBILITY.md`、讨论文档的 UNKNOWN 区 |
+| 体积（145.1 KB / 172 KB） | 由 `perf-gate.py` + `budget.json` 管，已有独立账本 | `docs/BUDGET.md` |
+| 源码行数、文件数 | 随重构波动，没有对外声明依赖它 | 不登记 |
+| CHANGELOG 里的历史数字 | 历史记录，改了就是篡改 | 不扫描 |
+
+**注释/文档字符串里的数字也不在判据范围内**（例如 `gen-docs.py` 顶部还写着"35 个组件的 README"）。判据只管**对外声明**；注释漂移不影响读者，但要改就顺手改，不要为了它加一条判据。
+
+---
+
+## 四、新增一项事实的步骤
+
+1. 确认它是**机器能可靠算出来的**。算不出来的，别加（见第三节）。
+2. 在 `05-audit/_facts.py` 的 `collect()` 里加一个键，值从源文件现算。
+3. 在 `validate_sources()` 里加对应的结构约束（否则源坏了会静默算出错数）。
+4. 如果它有对外声明，在 `CLAIMS` 里登记**位置**（文件 + 正则），不登记数值。
+   **正则只能用 `_num()` / `_labelled()` 拼**，不要自己写 `(\d+)`。
+   S24 会检查每个数字捕获组是否带规定的形状（见 §五·2 的注）。
+5. 如果是"标题 + 清单"这种成对出现的声明，登记到 `TIER_HEADINGS` / `LISTING_FILES`。
+6. 跑 `python 05-audit/facts-gate.py --write`，再跑 `python 05-audit/facts-gate.py`。
+7. 在 `--selftest` 里补一条合成样本，证明新判据在该红时会红。
+8. 更新本文件的登记表（只加行，不写数值）。
+
+---
+
+## 五、已知限制（不装作没有）
+
+1. **未登记扫描只覆盖 `SCAN_FILES` 里的 8 个文件**。`docs/*.md` 里如果新写一句"40 个组件"，不会被抓。要扩就把文件加进 `SCAN_FILES`。
+2. **数字与单位之间的形态有限**。认这些：
+   - `N components` / `N 个组件`
+   - `共 N 个`，**且 `个` 后面紧跟括号 / 句读 / 行尾**（`共 40 个（stable…）`、`共 37 个。`）
+   - `stable|beta|alpha N`
+   - 分节标题 `(N)` / `（N）`：`### primitives (17)`、`### recipes · 整页配方（5）`
+   - 以上**全部**容忍 Markdown 的 `**` `_` 反引号夹在标签与数字之间、或包住数字
+     （`stable **39**`、`### primitives (**16**)` 都认）
+
+   > 🔴 这条纪律现在是结构性的：所有数字提取只能经 `_num()`（数字在前）或
+   > `_labelled()`（标签在前）。`--selftest` 的 **S24** 比对的是**数字捕获组的
+   > 完整形状** `NUM_CORE`（前有可选强调符 + `(\d+)` + 后有可选强调符），
+   > 而不是"正则里出现过强调符字符类"——后者把强调符放到无关位置就能骗过。
+   >
+   > 但要说清楚它的边界：S24 证明的是"捕获组带规定形状"，**不是**"这个正则由
+   > `_num`/`_labelled` 生成"。后者需要解析正则语法，本阶段不做（不引入 AST、
+   > 不加依赖）。`--selftest` 的 **S24b** 反过来检查 S24 自己：坏形状要抓、
+   > 好形状不许误判——否则"S24 永远返回空"也会显示为通过。
+
+   不认："四十个组件"、"4 打组件"。
+   故意不认 `共 3 个步骤` 这类——`个` 后面接的是名词，省略的不是"组件"；
+   把它算进来会让「装好需要 3 个步骤」这种句子误报。要报数就写 `N 个组件`。
+   也故意不认 `一共就这么 37 个`——`共` 与数字不相邻就不算声明。
+3. **清单核对只覆盖两份 README**。`guide/*.html` 里的组件表是 `gen-docs.py` 生成的，与契约同源，不重复登记。
+4. **清单只比 id 集合，不比顺序**。顺序是排版偏好（两份 README 都按字母排，但不是事实）。
+5. **`facts.json` 本身可能被手改**。判据 ② 会抓（现算 ≠ 存储），但它不是加密的——能改文件的人也能改源码。这里防的是**疏忽**，不是**恶意**。
+6. **CLI 子命令数依赖 `node`**。`node` 不可用时这条会抛错而不是跳过——宁可红，不要静默绿。

package/docs/LAYER-BASELINE.md

@@ -1,6 +1,6 @@
 # `@layer` 的 WebView 基线（W12）
 
-> **当前状态：部分验证（7 行），且已出现 1 个阻塞样本。**
+> **当前状态：7 行真机人工实测，且已出现 1 个阻塞样本。**
 > 已有 7 行真机实测。**`@layer` 6 行通过、1 行不通过**：
 >
 > | 入口 | 结果 |
@@ -18,6 +18,14 @@
 >
 > 按下面第三节的判据：**已有一行 `@layer` 不通过 ⇒ 当前不能无条件切层**，
 > 只能走 `@supports at-rule(@layer)` 双写，或者不切。
+>
+> 🔍 **证据等级：人工实测，不是自动化覆盖。**
+> 这 7 行是在真实设备上打开探针页、人工录入的结果 —— 有完整 UA、可复跑，但**没有回归保护**：
+> 某个浏览器下次升级，不会有任何门禁因此变红。
+> ⇒ 它支撑的结论是「我们在这 7 个环境里试过，结果如下」，
+> 不是「我们保证这 7 个环境一直能用」。
+> 逐项结果（7 行 × 15 项）、15 项全集与复核方法见
+> [`10-review/webview/RESULTS.md`](../10-review/webview/RESULTS.md)。
 
 ---
 
@@ -132,6 +140,21 @@ Android 上 Chrome ≠ 系统 WebView ≠ 各家 App 内置 WebView。**入口
 | 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 |
 
+### 四·一、这 7 行的证据强度与复核
+
+| 问题 | 答案 |
+|---|---|
+| 数据怎么来的 | 在真实设备上打开 `10-review/webview/capability-probe.html`，把页面输出的结果贴进上表 |
+| 有没有原始记录 | 🔴 **没有入库**。当时探针把 JSON POST 回采集端，落的是本机文件，仓库里只留下转录进表格的结论 |
+| 逐项结果在哪看 | [`10-review/webview/RESULTS.md`](../10-review/webview/RESULTS.md) —— 7 行 × 15 项矩阵 |
+| 别人怎么复核 | 同上文件「怎么自己复核一行」：取 UA → 在目标设备复跑探针 → 比对 `N / 15` 与缺失项 |
+| 日期锚点 | 表格「测试日期」列写的是「见采集所在提交（git log）」；用 `git blame` + 该行 UA 的唯一片段定位 |
+| 有没有自动化守着 | **没有**。人工一次性实测，浏览器升级不会触发任何门禁 |
+
+⚠️ 上表「状态」列的 `VERIFIED` 是 `webview-probe-gate.py` 的**结构判据**（UA 完整可复核、无占位符、
+8 列齐全），**不是**「自动化验证过」。它和 `SUPPORT.md` 里的 `✅ 已验证` 同名不同义 ——
+读这一列时别把两者当成一回事。
+
 ---
 
 ## 五、刻意不写的东西
@@ -153,6 +176,8 @@ UA 是证据，版本传闻不是。
 |---|---|---|
 | `10-review/ios/index.html` | **观感与交互**在 Safari 下对不对（按钮、键盘弹起、暗色） | 人眼看，逐条对 |
 | `10-review/webview/capability-probe.html` | **能力**在目标 WebView 里有没有（`@layer` 等 15 项） | 机器判定，人只负责贴 JSON |
+| `10-review/webview/RESULTS.md` | 那 15 项**分别是什么**、每台设备**逐项**如何、别人怎么复跑一遍 | 随实测更新 |
 
-两者不能互相替代：能力全支持而观感崩了，和观感正常但 `@layer` 被整段丢弃，
-是两种完全不同的事故。
+三者不能互相替代：能力全支持而观感崩了，和观感正常但 `@layer` 被整段丢弃，
+是两种完全不同的事故；而"知道有 15 项"和"知道这 15 项各自是什么"也不是一件事 ——
+前者只是计数，后者才能判断某个缺失要不要紧。