agentcss 0.0.0-stage → 0.11.3

package/dist/09-assets/sparkline/sparkline.js

@@ -0,0 +1,265 @@
+(function () {
+'use strict';
+
+var NS = 'http://www.w3.org/2000/svg';
+var instances = [];
+
+function toArray(x) { return Array.prototype.slice.call(x); }
+function el(name, attrs) {
+var n = document.createElementNS(NS, name);
+if (attrs) for (var k in attrs) if (attrs.hasOwnProperty(k)) n.setAttribute(k, attrs[k]);
+return n;
+}
+function num(v, d) { var n = parseFloat(v); return isNaN(n) ? d : n; }
+
+function parsePoints(spark) {
+var raw = spark.getAttribute('data-spark') || '';
+if (!raw.trim()) return [];
+var parts = raw.split(',');
+var out = [];
+for (var i = 0; i < parts.length; i++) {
+var t = parts[i].trim();
+
+if (t === '' || t === '-' || t === 'null' || t === 'NaN') {
+out.push(null);
+continue;
+}
+var v = parseFloat(t);
+out.push(isNaN(v) ? null : v);
+}
+return out;
+}
+
+function readOpts(spark) {
+return {
+type: spark.getAttribute('data-spark-type') || 'line',
+height: num(spark.getAttribute('data-spark-height'), 32),
+color: spark.getAttribute('data-spark-color') || 'var(--accent)',
+fill: (spark.getAttribute('data-spark-fill') || 'yes') !== 'no',
+last: (spark.getAttribute('data-spark-last') || 'no') === 'yes',
+animate: (spark.getAttribute('data-spark-animate') || 'yes') !== 'no',
+};
+}
+
+function scale(points, w, h, pad) {
+
+var vals = [];
+for (var k = 0; k < points.length; k++) {
+if (points[k] !== null) vals.push(points[k]);
+}
+if (!vals.length) return null;
+var min = Math.min.apply(null, vals);
+var max = Math.max.apply(null, vals);
+
+if (max === min) { max = min + 1; min = min - 1; }
+var span = max - min;
+var n = points.length;
+var xs = [], ys = [];
+for (var i = 0; i < n; i++) {
+xs.push(n === 1 ? w / 2 : pad + (w - pad * 2) * (i / (n - 1)));
+
+ys.push(points[i] === null ? null
+: h - pad - (h - pad * 2) * ((points[i] - min) / span));
+}
+return { xs: xs, ys: ys, min: min, max: max };
+}
+
+function supportsReducedMotion() {
+return typeof window.matchMedia === 'function' &&
+window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+function draw(spark) {
+var pts = parsePoints(spark);
+
+var wQuick = Math.round(spark.getBoundingClientRect().width);
+var sigQuick = wQuick + '|' + (spark.getAttribute('data-spark') || '');
+var isFirstQuick = spark.__sparkSig === undefined;
+if (!isFirstQuick && spark.__sparkSig === sigQuick && spark.firstChild) {
+return;
+}
+
+var old = spark.firstChild;
+while (old) { var n = old.nextSibling; spark.removeChild(old); old = n; }
+if (pts.length < 2) return;
+
+var o = readOpts(spark);
+
+var w = Math.round(spark.getBoundingClientRect().width)
+|| spark.clientWidth
+|| num(spark.getAttribute('data-spark-width'), 120);
+var h = o.height;
+
+spark.__sparkSig = sigQuick;
+
+spark.style.setProperty('--spark-h', h + 'px');
+
+var LAST_R = 2.5;
+var LAST_BAR = 3;
+
+var pad = o.last ? (LAST_R + 1.5) : 1;
+var s = scale(pts, w, h, pad);
+
+if (!s) return;
+if (s.xs.length < 2) return;
+
+var svg = el('svg', {
+width: '100%', height: h,
+viewBox: '0 0 ' + w + ' ' + h,
+
+'aria-hidden': 'true',
+focusable: 'false',
+});
+
+var segs = [], cur = [];
+for (var i = 0; i < s.xs.length; i++) {
+if (s.ys[i] === null) {
+if (cur.length) segs.push(cur);
+cur = [];
+} else {
+cur.push(i);
+}
+}
+if (cur.length) segs.push(cur);
+
+var total = 0;
+for (var q = 0; q < segs.length; q++) total += segs[q].length;
+if (total < 2) { spark.appendChild(svg); return; }
+
+function pathOf(seg) {
+var d = 'M' + s.xs[seg[0]].toFixed(1) + ' ' + s.ys[seg[0]].toFixed(1);
+for (var t = 1; t < seg.length; t++) {
+d += 'L' + s.xs[seg[t]].toFixed(1) + ' ' + s.ys[seg[t]].toFixed(1);
+}
+return d;
+}
+
+if (o.type === 'area' && o.fill) {
+var base = h - pad;
+for (var g = 0; g < segs.length; g++) {
+var sg = segs[g];
+if (sg.length < 2) continue;
+var ad = pathOf(sg) +
+'L'+ s.xs[sg[sg.length - 1]].toFixed(1) + ' ' + base +
+'L'+ s.xs[sg[0]].toFixed(1) + ' ' + base + 'Z';
+var ap = el('path', { d: ad, 'class': 'spark-area', 'fill-opacity': '0.14' });
+ap.style.setProperty('--spark-c', o.color);
+svg.appendChild(ap);
+}
+}
+
+if (o.type === 'bar') {
+var bw = Math.max(1, (w - pad * 2) / pts.length - 1);
+for (var j = 0; j < s.xs.length; j++) {
+
+if (s.ys[j] === null) continue;
+var bh = h - pad - s.ys[j];
+var rc = el('rect', {
+x: (s.xs[j] - bw / 2).toFixed(1), y: s.ys[j].toFixed(1),
+width: bw.toFixed(1), height: Math.max(0, bh).toFixed(1),
+'class': 'spark-bar',
+'fill-opacity': j === s.xs.length - 1 ? '1' : '0.72',
+});
+rc.style.setProperty('--spark-c', o.color);
+svg.appendChild(rc);
+}
+} else {
+for (var m = 0; m < segs.length; m++) {
+var seg = segs[m];
+if (seg.length === 1) {
+
+var dc = el('circle', {
+cx: s.xs[seg[0]].toFixed(1), cy: s.ys[seg[0]].toFixed(1), r: '1.5',
+'class': 'spark-dot',
+});
+dc.style.setProperty('--spark-c', o.color);
+svg.appendChild(dc);
+continue;
+}
+
+var path = el('path', {
+d: pathOf(seg),
+'class': 'spark-line',
+'stroke-width': '1.5',
+'stroke-linecap': 'round', 'stroke-linejoin': 'round',
+'vector-effect': 'non-scaling-stroke',
+});
+path.style.setProperty('--spark-c', o.color);
+
+if (o.animate && !supportsReducedMotion() && isFirstQuick) {
+
+path.classList.add('spark-anim');
+}
+svg.appendChild(path);
+}
+}
+
+var li = s.xs.length - 1;
+if (o.last && s.ys[li] !== null) {
+var lc = el('circle', {
+cx: s.xs[li].toFixed(1), cy: s.ys[li].toFixed(1), r: String(LAST_R),
+'class': 'spark-dot',
+});
+lc.style.setProperty('--spark-c', o.color);
+svg.appendChild(lc);
+}
+
+spark.appendChild(svg);
+}
+
+var Chart = {
+draw: draw,
+emit: function (spark) { draw(spark); },
+
+update: function (root) {
+var list = (root || document).querySelectorAll('.sparkline[data-spark]');
+for (var i = 0; i < list.length; i++) draw(list[i]);
+},
+};
+window.Chart = Chart;
+
+function init() { Chart.update(); }
+
+if (typeof window.ResizeObserver === 'function') {
+var ro = new window.ResizeObserver(function (entries) {
+for (var i = 0; i < entries.length; i++) {
+var el = entries[i].target;
+if (el && el.className && el.className.indexOf('sparkline') > -1) {
+draw(el);
+}
+}
+});
+
+function observeAll() {
+var list = document.querySelectorAll('.sparkline[data-spark]');
+for (var i = 0; i < list.length; i++) {
+try { ro.observe(list[i]); } catch (e) {  }
+}
+}
+if (document.readyState === 'loading') {
+document.addEventListener('DOMContentLoaded', observeAll);
+} else {
+observeAll();
+}
+
+Chart.observe = function (el) {
+if (el) { try { ro.observe(el); } catch (e) {  } }
+else observeAll();
+};
+} else {
+
+window.addEventListener('resize', function () { Chart.update(); });
+}
+
+if (document.readyState === 'loading') {
+document.addEventListener('DOMContentLoaded', init);
+} else {
+init();
+}
+
+var t = null;
+window.addEventListener('resize', function () {
+if (t) clearTimeout(t);
+t = setTimeout(function () { Chart.update(); }, 150);
+});
+})();

package/dist/COSTS.md

@@ -0,0 +1,56 @@
+# 采纳成本表
+
+> 这个文件由 `05-audit/dist-cost-gate.py` **生成**，不要手改（改了门禁会红）。
+> 数字口径：**dist 里的 min 产物，gzip 9 级**。
+
+## 一、为什么单独算这一笔
+
+采用一个组件要付三笔钱：`tokens`（必付）+ 组件 CSS + 组件 JS（可选）。
+
+实测两笔账，一笔不省：
+
+- `tokens` 源码版 gzip **18.1 KB** → min 版 **2.6 KB**（省 85%）——
+  源码多的那部分**全是注释**（全库 CSS 有 66% 是注释，字节口径），而注释是给我们的，不是给使用者浏览器的。
+- tokens 的 min 版 2.6 KB **比任何一个组件自己都贵** ⇒
+  "只用一个组件"的真实起步价就是它。不公开这张表，等于让人盲买。
+
+## 二、明码标价
+
+| 档 | 组件 | tokens（必付） | CSS | JS | **合计** | 源码版合计 | 差 |
+|---|---|---:|---:|---:|---:|---:|---:|
+| primitive | `badge` | 2.6 KB | 0.5 KB | — | **3.1 KB** | 20.8 KB | −17.7 KB |
+| primitive | `button` | 2.6 KB | 1.0 KB | — | **3.6 KB** | 24.3 KB | −20.7 KB |
+| primitive | `card` | 2.6 KB | 0.9 KB | — | **3.6 KB** | 21.6 KB | −18.0 KB |
+| primitive | `choice` | 2.6 KB | 1.1 KB | — | **3.7 KB** | 23.5 KB | −19.7 KB |
+| primitive | `combobox` | 2.6 KB | 1.0 KB | 5.4 KB | **9.0 KB** | 27.7 KB | −18.8 KB |
+| primitive | `date-range` | 2.6 KB | 0.8 KB | 2.5 KB | **6.0 KB** | 24.5 KB | −18.6 KB |
+| primitive | `input` | 2.6 KB | 1.0 KB | — | **3.6 KB** | 21.7 KB | −18.0 KB |
+| primitive | `popover` | 2.6 KB | 0.8 KB | 2.1 KB | **5.6 KB** | 25.6 KB | −20.0 KB |
+| primitive | `progress` | 2.6 KB | 0.7 KB | — | **3.3 KB** | 20.9 KB | −17.6 KB |
+| primitive | `select` | 2.6 KB | 0.8 KB | 3.5 KB | **6.9 KB** | 27.9 KB | −20.9 KB |
+| primitive | `separator` | 2.6 KB | 0.2 KB | — | **2.9 KB** | 19.3 KB | −16.5 KB |
+| primitive | `skeleton` | 2.6 KB | 0.5 KB | — | **3.1 KB** | 19.5 KB | −16.4 KB |
+| primitive | `switch` | 2.6 KB | 0.8 KB | — | **3.4 KB** | 25.2 KB | −21.8 KB |
+| pattern | `accordion` | 2.6 KB | 1.3 KB | 1.7 KB | **5.7 KB** | 31.9 KB | −26.2 KB |
+| pattern | `content` | 2.6 KB | 1.0 KB | — | **3.6 KB** | 22.6 KB | −19.0 KB |
+| pattern | `drawer` | 2.6 KB | 0.8 KB | 2.0 KB | **5.4 KB** | 23.4 KB | −18.1 KB |
+| pattern | `dropdown` | 2.6 KB | 0.8 KB | 2.9 KB | **6.3 KB** | 26.3 KB | −20.0 KB |
+| pattern | `form-validation` | 2.6 KB | 0.8 KB | — | **3.4 KB** | 22.6 KB | −19.2 KB |
+| pattern | `list` | 2.6 KB | 0.6 KB | — | **3.2 KB** | 20.5 KB | −17.2 KB |
+| pattern | `nav` | 2.6 KB | 1.2 KB | 2.6 KB | **6.5 KB** | 29.2 KB | −22.8 KB |
+| pattern | `overlay` | 2.6 KB | 1.1 KB | 2.8 KB | **6.6 KB** | 32.0 KB | −25.4 KB |
+| pattern | `pagination` | 2.6 KB | 0.8 KB | 2.6 KB | **6.0 KB** | 28.3 KB | −22.4 KB |
+| pattern | `reveal` | 2.6 KB | 0.3 KB | 1.1 KB | **4.1 KB** | 22.5 KB | −18.4 KB |
+| pattern | `states` | 2.6 KB | 0.8 KB | — | **3.5 KB** | 22.1 KB | −18.6 KB |
+| pattern | `tabs` | 2.6 KB | 0.7 KB | 2.0 KB | **5.3 KB** | 25.0 KB | −19.7 KB |
+| pattern | `tooltip` | 2.6 KB | 0.5 KB | 1.9 KB | **5.0 KB** | 24.7 KB | −19.7 KB |
+| pattern | `tree` | 2.6 KB | 0.6 KB | 2.9 KB | **6.2 KB** | 25.7 KB | −19.5 KB |
+
+## 三、全库
+
+- 全部组件都用上（min，含 tokens 一份）：**60.0 KB**
+- 源码版（带注释）全库 gzip：288.4 KB
+
+> ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 66% 是注释，字节口径）。
+> 它的用途只有一个 —— 让人看清"dist 到底省了多少"。
+

package/docs/AI-CONTRACT.md

@@ -0,0 +1,197 @@
+# AI 编辑契约
+
+> **这份文件是给「正在修改本库或其使用者页面」的人与 AI 看的操作边界。**
+> 不是风格指南，是**硬约束**。违反其中任何一条，库里的门禁会红。
+
+---
+
+## 为什么需要这份文件
+
+一次真实事故：用本库做 14 页 PPT，AI 反复局部修改后整体崩坏，
+人工修复 1.5 小时仍未收口。
+
+复盘结论：**问题不在模型不够聪明，而在系统没有划定修改边界。**
+库约束了「浏览器里怎么表现」，但没有约束「CSS 能写在哪」——
+于是模型可以随手写 `a { color: blue }`，把宿主全站链接改掉。
+
+⇒ 本库能做的不是「保证 AI 不犯错」，是**让 AI 犯的错有上限**。
+
+---
+
+## 一、七条硬约束
+
+| # | 规则 | 为什么 | 门禁 |
+|---|---|---|---|
+| 1 | **不得写裸标签选择器**（`a {}` `h1 {}` `button {}`） | 作用域是整个文档 ⇒ 会改掉宿主页面所有同名元素 | `bleed-gate.py` |
+| 2 | **不得新增裸颜色 / 裸间距** | 一旦绕过令牌，暗色模式立刻失效 | `hardcode-gate.py` |
+| 3 | **不得修改 `tokens.css`**（除非任务明确要求改令牌） | 它是全库配色/字号/间距的源头，改它=改整个项目 | `impact-report.py` |
+| 4 | **不得新增页面级 override 链**（`.page-3 h1 {...}` 叠加） | 局部改动必须对全局无副作用 | `bleed-gate.py` + 视觉回归 |
+| 5 | **组件改动必须重跑该组件的视觉基线** | 行为契约抓不到「样式被改坏」 | `shot-baseline.py` |
+| 6 | **组件不得自己造 DOM 事件**（`new CustomEvent` / `createEvent`） | 老 WebView 没有 `CustomEvent` 构造函数 ⇒ 在**用户交互路径上**抛异常，本地测不出来。唯一入口是 `flEmit` | `emit-check.js` 判据 ⑨ |
+| 7 | **不得在注释/示例里写不存在的 API**（含 `data-on-*` 这种"属性当回调"） | 用法示例会被照抄；`pg.on(...)` 这种从来没实现过的写法 ⇒ 运行时 `is not a function`。HTML 属性里放不出函数，`data-on-*` 物理上只能是死代码 | `api-form-gate.py` 判据 5 · `emit-check.js` 判据 ⑩ |
+
+> 第 6 条为什么值得单独列：它不是风格问题。
+> 自己写 `new CustomEvent(...)` 在 Chrome 里**一切正常**，
+> 只在真机上表现为"点了没反应"，而且控制台不一定有线索。
+> ⇒ 这类"本地全绿、真机崩"的改动，正是这份契约要挡的东西。
+>
+> 第 7 条是同一类：**本地全绿、别人照抄就崩**。
+> 本库已经有过两次这种事故（`is-*` 状态类、pagination 的 `pg.on`），
+> 它们的共同点是"说有、实现里没有"，而没有任何门禁在比对这两者。
+
+---
+
+## 二、修改之前先看影响范围
+
+```bash
+python3 05-audit/impact-report.py           # 我刚改了哪些文件
+python3 05-audit/impact-report.py --staged # 只看暂存区
+```
+
+它会明确告诉你：
+
+```
+🔴 全局影响（必须全量回归）
+   01-tokens/tokens.css    令牌层：全库配色/间距/字号的源头
+   ⇒ 必须通过：bleed contrast dark-cont visual
+
+🟡 局部影响（只需检查这些）
+   03-patterns/content/content.css    组件样式：仅该组件的页面
+   ⇒ 需要重跑视觉回归：03-patterns/content/demo.html
+```
+
+**不要凭感觉决定要不要跑回归。** 这条命令就是为此存在的。
+
+---
+
+## 三、局部修改的标准动作
+
+以「改第 3 页的标题」为例：
+
+```bash
+# 1. 先看范围
+python3 05-audit/impact-report.py
+
+# 2. 只改该页面的文件，不要碰共享层
+
+# 3. 只跑相关的门禁
+MODE=fast bash 05-audit/check-all.sh
+python3 05-audit/shot-baseline.py --check    # 视觉基线
+
+# 4. 确认没波及别处
+python3 05-audit/impact-report.py           # 应当仍然全是局部
+```
+
+❌ 反面做法（事故里的实际路径）：
+
+```css
+/* 为了修第 3 页 */
+h1 { font-size: 31px }          /* 改一个，14 页全变 */
+.slide-3 h1 { font-size: 31px } /* 于是开始堆页面级 override */
+.slide-4 h1 { font-size: 32px } /* ……一路滑向灾难 */
+```
+
+⇒ **正确的修法是改组件，不是改页面。**
+如果你发现自己在写 `.slide-N xxx`，停下来 —— 那是信号。
+
+---
+
+## 四、布局应该用组件，不是自由发挥
+
+本库提供的是**组件**，不是自由布局。
+要表达「两栏」「卡片网格」，用现有组件组合，不要自己写宽度。
+
+```html
+<!--✅ 用组件组合 -->
+<div class="card"><div class="card__body">…</div></div>
+
+<!--❌ 自己发明布局：magic number 谁都维护不了 -->
+<div style="width: 612px; margin-left: 37px; transform: translateX(19px)">
+```
+
+**理由**：magic number 无法被门禁检查，也无法在暗色模式下自适应。
+本库现有的令牌与组件已经覆盖常见场景；找不到合适的场景时，
+**加一个组件**比在页面里调数值更省事。
+
+---
+
+## 五、什么时候该停下来问
+
+以下情况不要自行决定，停下来确认：
+
+- 需要修改 `01-tokens/tokens.css`（影响全局）
+- 需要绕过某个门禁（说明门禁要么错了、要么设计要改）
+- 一个组件要加第三种视觉变体（先确认能不能用现有变体组合）
+- 某个问题「改A 坏了，改 B 也坏了」（可能是耦合，需要先查依赖）
+
+---
+
+## 六、这套约束的边界（诚实说明）
+
+**本库做不到的事**：
+
+- ❌ 约束使用者在**自己项目**里写的 CSS —— 那些文件不在本库仓库里
+- ❌ 替代人工设计判断 —— 布局是否「好看」不是机械判据
+- ❌ 保证任何模型不犯错 —— 只能保证它犯的错**有上限、有据可查**
+
+**为什么还要做**：因为「有上限」和「没上限」在真实工作量上是天壤之别。
+事故里 1.5 小时修不完，恰恰是因为错误**没有边界**。
+
+---
+
+## 六·五、这份文档的层次
+
+⚠️ 本节上面的内容是 **Guidance**（建议）。它可以整份推翻，不动门禁。
+
+真正不能被推翻的是另外两层：
+
+| 层 | 在哪 | 怎么改 |
+|---|---|---|
+| **不变式**（客观事实） | `INVARIANT.md` | 改不了，除非物理定律变了 |
+| **契约**（约定） | `ai/*.json` + `API.md` | 发个版本就能改 |
+| **建议**（这里） | `GUIDANCE.md` + 本文件 | 随时可整份作废 |
+
+为什么分三层：**约束如果只有一层，今天的约束就是明天的天花板。**
+模型变强、做法变化时，放宽的是建议层，不变式一个字都不用动。
+
+⇒ 如果你在写自动化工具，请读 `ai/` 下的机器可读契约，而不是解析这份散文。
+
+## 七、给 AI 的极简版（贴进 system prompt 即可）
+
+```
+遵守以下编辑边界：
+1. 不写裸标签选择器（a{} h1{} button{}）——一律挂组件根类
+2. 不新增裸颜色与裸间距——用 tokens
+3. 不改 01-tokens/tokens.css，除非任务明确要求改令牌
+4. 不写 .page-N .xxx 这类页面级 override 链
+5. 改组件样式后必须重跑该组件的视觉基线
+6. 改之前先跑 impact-report.py 看影响范围
+7. 状态一律写 data-state 属性，不写状态类名（见 API.md 迁移表）
+发现自己在写页面级 override ⇒ 停下来，改组件
+```
+
+机器的版本在这里（**优先用它**，不用解析上面的散文）：
+
+- `ai/components.json` / `ai/tokens.json` —— 组件与令牌的结构化事实
+- `ai/validate.js` + `node ai/cli.js check <文件>` —— 零依赖校验
+- `ai/profiles.json` —— 三档严格程度；`strict` 只允许 `stable` 组件
+- `ai/capabilities.json` —— 按**能力**协商可用操作，不按模型名分支
+- `ai/behaviors.json` —— **行为覆盖矩阵**：哪些组件必须有哪种微行为
+  （状态：`core` 已收编 / `manual` 手写未收编 / `gap` 应做未做 / `n/a` 不适用）
+  ⇒ **不登记就红**，不许靠省略跳过；`manual` 与 `gap` 的数量有棘轮，只能降不能升
+- **`maturity`（成熟度）是算出来的，不是拍的** —— 每个组件有一个
+  `maturity`（`alpha` / `beta` / `stable`）和一份 `maturityReasons`。
+  四条判据：有 `demo.html` · 有专属门禁 · 状态全在 `data-*` 属性上（I-8）
+  · **行为零欠账**（矩阵里没有 `manual` / `gap`）。
+  ⇒ 手写把某个组件改成 `stable` 而它还欠着账，门禁会红（`05-audit/maturity-gate.py`）。
+  ⇒ ⚠️ `strict` 档位只放行 `stable`：欠着账的组件在 `strict` 下**不可用**，
+     这是有意的 —— 要用就切 `standard`，并接受它们可能还有手写副本。
+- `ai/deprecations.json` —— **废弃登记册**：库里曾经有 / 现在有但将来要删的公开名字
+  （令牌名 / 类名）。移除公开名字是破坏性变更，必须走流程：
+  登记（`deprecatedIn`）→ **跨至少一个次版本**的迁移窗口 → 到 `removeIn` 才允许删。
+  判据双向看住（`05-audit/deprecation-gate.py`）：到期没删红、提前删也红。
+  ⇒ `ai/surface.baseline.json` 是公开面基线，**只增不减** —— 否则"先删代码再更新基线"
+     就能把未登记的移除洗白。
+
+  ⚠️ 诚实边界：我们没有 codemod、也没有运行时告警，所以这个"窗口"只是**版本号承诺**，
+     不是技术阻断。要真的拦截，得自己在 CI 里加 lint。

package/docs/BACKLOG.md

@@ -0,0 +1,127 @@
+# 待办与判定台账（BACKLOG）
+
+> 这份文件只回答三个问题：
+> **① 那些"好想法"哪些已经落地、由什么守着；② 哪些裁定不做、什么条件下重开；
+> ③ 哪些是环境边界（不是待办，别再当 TODO 挂着）。**
+>
+> 它的存在理由：这些结论原本散在四份报告里（交付报告 / huxx 借鉴评审 /
+> 合并评审 / 交接单），要翻完才知道还剩什么。于是同一件事被反复讨论、
+> 已被判"不做"的又被重新提出来做一遍。
+>
+> ⚠️ **本文件不写会变的数字**（门禁数、自检数、组件数）。要给数字，
+> 就跑对应的门禁看它的输出 —— 数字只有运行时一个出处（I-7）。
+
+---
+
+## 一、已落地（每一项都有门禁守着，不是"写过"）
+
+| 能力 | 落点 | 守着它的判据 |
+|---|---|---|
+| 入场动效（六方向、位移 ≤8px、默认不接管、只播一次） | `03-patterns/reveal/` | `reveal-contract.js`（10 条）+ `motion.py --reduced-audit` |
+| 减少动效三档（位移必停 / 真实进度必留 / 颜色压到 `--dur-fast`） | `01-tokens/` 令牌层一条覆盖规则 | `motion.py`（三向核对，非文件计数） |
+| 详情页三变体（full / partial / null 同构） | `04-recipes/detail-page/` | `detail-page-contract.py`（标签序列逐项比对 + 视觉覆盖） |
+| 无数据是一等状态（不隐藏、不拿 0 冒充、必须给理由、版面不塌） | 同上 `null.html` | `no-data-gate.py` |
+| 新页面必须进视觉基线（防"新配方无人看管"） | `05-audit/visual-coverage-gate.py` | 自身 `--selftest` + 反向控制 |
+| 视觉基线防"改注释也算变更" | `shot-baseline.py` 的 `css_fingerprint()` | 剥注释/去空行后再哈希 |
+| 包内闭包 + 消费者侧解析 | `pack-closure.js` / `entry-resolve.js` | `pack-closure` / `pkg-resolve`（判"消费者真去解析"） |
+| 自动初始化写成契约（每个全局逐个写明 是 / 条件 / 否） | `API.md`「自动初始化」+ 源码 `@autoinit` 标记 | `autoinit-gate.py`（三条判据，双向） |
+| 门禁自己也要有牙（反向控制被真的跑到） | `behavior-reverse.sh` + `selftest-all.py` | `selftest-all`（元门禁）+ `selftest-all-rev` |
+| 文档事实与仓库一致（组件数 / 门禁数 / stable·beta） | `05-audit/doc-facts-gate.py` | 自身 `--selftest` |
+| 真机能力矩阵（每一行都是 VERIFIED） | `docs/LAYER-BASELINE.md` | `webview-probe-gate.py`（清单与源码双向） |
+
+---
+
+## 二、本轮（autoinit 契约那一轮）做的事
+
+| 事 | 性质 | 证据 |
+|---|---|---|
+| `selftest-all` 自备 `:8000`（canary 字节比对 + 退出时关掉） | **修真实缺陷**：fast 档无服务 ⇒ 一条自检假红，红的原因与检查内容无关 | `python 05-audit/selftest-all.py` → 全部通过 |
+| 判定抽成 `verdict()` + 判据 ④「跑不起来 ≠ 通过」 | 新增牙：`RC=0` 但输出说跑不起来，判红 | 自带 `--selftest` 样本 |
+| `dead-class-gate --selftest` 接进 `behavior-reverse.sh` | 补 P2 欠账：它有自检但**从没被跑过** | `behavior-reverse.sh` |
+| 自动初始化契约 + `autoinit-gate` | 把 P3 的误判转成真闭环：**不改行为**，只补文档与判据 | 每个破坏样本都判对 |
+| `CONTRIBUTING` 两处过时数字 | 一处被 `doc-facts` 抓到，一处（散文标题 `159 道`）判据够不着 ⇒ 改成不写数字 | `doc-facts-gate` 绿 |
+| `ERRORS.md` E56 / E57 | 判据前提要自己造；注释不写会变的数量 | 台账 |
+
+---
+
+## 三、裁定不做（附重开条件）
+
+| 事项 | 为什么不做 | 什么条件下重开 |
+|---|---|---|
+| **T4 全局事件总线** | 没有第二个消费者（图表不订阅主题切换）。为一个假想消费者加全局单例，是把"零依赖"换成"零依赖但有隐含全局状态" | 出现**第二个真实消费者**（例如表格排序要通知图表重绘），且实现 ≤30 行 |
+| **View Transitions** | 真机基线含 **Chromium 97**（百度浏览器），而它要 111+。收益是"更好看"不是"更能用" | 有 Chromium 97–111 区间的实测基线，且能给出降级路径 |
+| **装饰层兄弟门禁**（`deco-sibling`） | 库里只有 **1 个**装饰层节点（`.detail-hero__deco`），且它已经做对了（`pointer-events:none` + `aria-hidden` + 空 div）。门禁判据只能靠 `deco` 这个**命名约定**触发 —— 第二个人把那层叫 `.hero__glow` 就漏了。**靠命名的守卫是弱判据**，不如不建 | 出现第 2 个装饰层，且命名不统一 ⇒ 改成**形态判据**（绝对定位 + 覆盖父容器 + 无文本/无交互子树），不再看名字 |
+| **滚动位置还原**（S5） | 实测三组 A/B/C 全部 `1600 → 1600`：桌面 Chromium 后退走 **bfcache** 整页恢复，脚本那段根本不需要跑。按"无法实测不合并"回退，没有留死代码 | 有**不走 bfcache** 的目标（旧 WebView），或页面返回后必然重渲染 |
+| **给 9 个 create-only 组件加自动初始化**（P3 的 A 方案） | 自动初始化拿不到 `options` ⇒ 给一个"看起来能用、行为不对"的默认实例，比不初始化更坏；且会与用户手写的 `create` **双初始化**（双重事件、泄漏） | 组件出现"零配置也能正确工作"的形态（例如全部改由 `data-*` 驱动），且能给出去重机制 |
+| **把散文里的数字也纳入 doc-facts** | 实测全库 6 处「NNN 道」，其中 4 处是**历史事故记录**（本来就是旧数字，改了才是篡改）。扩宽正则只会误伤历史叙述 —— 判据咬错人比不咬更坏 | 文档里出现"当前值"与"历史值"可区分的写法约定（例如统一 `@fact:` 标记），再据标记判 |
+
+---
+
+## 四、环境边界（不是待办，别再挂 TODO）
+
+这三件事**代码侧已经就绪或已到边界**，缺的是外部条件。写在这里是为了
+下次不再重新讨论一遍"要不要做""是不是没做"。
+
+### 4.1 真机覆盖：只到现有矩阵，不再扩
+
+| 已有（全部 VERIFIED） | 缺口 |
+|---|---|
+| iPhone Safari / iPad Safari / iPad 微信 / iPad 企微 / Android 微信（XWEB 146）/ Android 百度浏览器（Chromium 97） | Android **系统浏览器 / 其它 App 内置内核**（抖音、小红书、支付宝…） |
+
+**为什么不再扩**：国内环境下拿不到稳定的 Android 系统浏览器与 Google 组件，
+云真机又要实名与费用；使用者能提供的机器已经全部采过。
+
+**在现有条件下已经做到了什么（这些不需要新设备）**：
+
+1. **语法下限**：`es5-gate.py` 保证库代码不会用到 Chromium 97 不认识的语法。
+2. **特性探测而非 UA 猜测**：`@layer` 不可用时整层回退（`LAYER-BASELINE.md` 已记录
+   Chromium 97 **不支持 `@layer`** 这条阻塞项，并按"每一行都通过才无条件切"处理）。
+3. **能力探针页可复用**：`10-review/webview/capability-probe.html` 是自包含的，
+   任何人用手机自带浏览器打开就能采一行；采集结果按 `LAYER-BASELINE.md`
+   的表头填（必须写清**从哪个入口**打开）。
+4. **不虚构结论**：没有实测的内核一律标 `UNVERIFIED`，不写成"应该没问题"。
+
+### 4.2 npm 发布
+
+代码与发布脚本已就绪（`05-audit/publish.sh`，`.npmrc` 钉官方源）。
+缺的是账号 + 2FA 的人工动作。**注意历史坑**（`ERRORS.md` E55）：
+publish 返回 0 之后 registry 可能仍显示旧占位，**不要据此删包**。
+
+### 4.3 W13 真模型跑批
+
+工具链封闭（记录 v2 / 八条判据 / `models/reference.json` 必须 10/10），
+**记录数 0 ⇒ UNVERIFIED**。缺的是模型 API 访问权。现有结论（"一次生成半分到
+一毛钱，瓶颈是轮次不是 token"）来自人工实测，不是跑批。
+
+---
+
+## 五、如果还要往前推，按性价比排序
+
+| 顺序 | 事项 | 为什么值得 | 前置 |
+|---|---|---|---|
+| 1 | **把 `docs/ROADMAP.md` 的评分表按真值重写** | 它现在还写着「运行时描述符比对待做（W3）」「npm ci + WebKit 待做（W7）」「事实门禁待做（W4）」，而这三项**实测都已完成**（`api-form-gate` 消费 `global-api-probe`；CI 有 `npm ci` + nightly webkit 矩阵；`doc-facts-gate` 在跑）。过时的路线图会让下一个人重做一遍 | 无 |
+| 2 | 真机矩阵补一行（任何人的手机自带浏览器） | 成本 5 分钟，直接减少一个 `UNVERIFIED` | 一台能扫二维码的手机 |
+| 3 | 把 `capability-probe` 的采集流程写成一页 SOP | 现在采集格式只写在表格里，靠人猜 | 无 |
+| 4 | 次要：`ERRORS.md` 按"触发面"重新索引 | 查"我是不是又要犯某条"很不方便 | 无 |
+
+---
+
+## 六、怎么复查这份台账
+
+```bash
+cd <仓库根>
+
+# ① 已落地的东西还在不在（全量，约 10 分钟）
+MODE=full bash 05-audit/check-all.sh
+
+# ② 判据有没有牙（含本轮新增的 autoinit / selftest-all / dead-class）
+python 05-audit/selftest-all.py
+bash 05-audit/behavior-reverse.sh
+
+# ③ 文档说的和仓库是不是一回事
+python 05-audit/doc-facts-gate.py
+python 05-audit/autoinit-gate.py
+```
+
+**判定纪律**：本文件里说"已落地"的条目，如果哪天门禁红了，以门禁为准 ——
+台账只是索引，不是证据。