agentcss 0.26.0 → 0.27.0

package/ai/validate.js

@@ -32,7 +32,11 @@ var path = require('path');
 var AI_DIR = __dirname;
 
 // ---------------------------------------------------------------- 能力白名单
-// ⚠️ 改这个表 = 改工具的能力边界。加关键字 ⇒ 必须同时实现它，否则别加。
+// ⚠️ 改这个表 = 改工具的能力边界。
+//   🔴 表里有的关键字**必须真的实现**：白名单只负责"允许出现"，
+//      不负责"校验它"。两者不一致 ⇒ schema 里写了、校验器当没看见 ⇒ **静默假绿**。
+//      （本轮审计 F4：`uniqueItems` / `not` 在表里挂了很久但没实现，
+//        `validate({type:'array',uniqueItems:true},[1,1])` 返回 ok:true。）
 var SUPPORTED_KEYWORDS = [
   '$schema', '$id', '$comment', '$ref', 'definitions', 'title',
   'type', 'required', 'properties', 'additionalProperties', 'patternProperties',
@@ -57,15 +61,30 @@ function isPlainObject(v) {
  */
 // 哪些键的"值"本身还是 schema
 var SUBSCHEMA_KEYS = [
-  'items', 'additionalProperties', 'patternProperties', 'allOf', 'anyOf',
+  'items', 'additionalProperties', 'allOf', 'anyOf',
   'oneOf', 'not', 'propertyNames', 'contains', 'if', 'then', 'else'
 ];
-// 哪些键是"名字 → schema"的容器（它们的**键**是字段名，不是关键字）
-var CONTAINER_KEYS = ['properties', 'definitions', '$defs', 'dependentSchemas'];
+/* 哪些键是"名字 → schema"的容器：它们的**键**不是关键字。
+   🔴 `patternProperties` 必须在这里，不能当普通子 schema ——
+      它的键是**正则**（`^--[a-z][a-z0-9-]*$`），
+      当成关键字检查就会报"用了没实现的关键字"，而 schema 本身完全合法。
+      这个错 0.26.0 就有，只是预扫当时只覆盖 4 份文件、碰巧都没用 patternProperties
+      ⇒ 直到本轮把预扫扩到全部 8 份才暴露（`tokens.audience` 第一个撞上）。 */
+var CONTAINER_KEYS = ['properties', 'definitions', '$defs', 'dependentSchemas',
+                      'patternProperties'];
+
+/* 扫哪些文件：**目录里现找**，不手写清单。
+   手写清单必漂 —— 0.26.0 时 `ai/` 下有 8 份 schema，这里只列了 4 份
+   （behaviors / deprecations / tokensAudience / tokensTree 从来没被扫过），
+   于是那四份里出现未知关键字也不会有人知道。 */
+function schemaFiles() {
+  return fs.readdirSync(AI_DIR).filter(function (f) {
+    return /\.schema\.json$/.test(f);
+  }).sort();
+}
 
 function assertSchemasUseOnlySupported() {
-  var files = ['contract.schema.json', 'components.schema.json',
-               'tokens.schema.json', 'patch.schema.json'];
+  var files = schemaFiles();
   var unknown = [];
 
   function checkNode(schema, f, ptr) {
@@ -118,6 +137,27 @@ function typeOk(expected, value) {
   return true;
 }
 
+/* JSON Schema 的"相等"是**深比较**：`{a:1}` 与 `{a:1}` 是两个对象但相等。
+   用 `===` 判重会把重复项全放过，而且是静默的。 */
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    for (var i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
+    return true;
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    var ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.length !== kb.length) return false;
+    for (var j = 0; j < ka.length; j++) {
+      if (!Object.prototype.hasOwnProperty.call(b, ka[j])) return false;
+      if (!deepEqual(a[ka[j]], b[ka[j]])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
 function resolveRef(root, ref) {
   if (ref.charAt(0) !== '#' || ref.indexOf('#/') !== 0) {
     throw new Error('只支持文档内 $ref：' + ref);
@@ -178,6 +218,18 @@ function validate(schema, data, root, ptr, errors) {
     if (schema.maxItems !== undefined && data.length > schema.maxItems) {
       errors.push({ path: ptr, msg: '元素多于 ' + schema.maxItems + ' 个' });
     }
+    /* `uniqueItems: true` = 元素两两不相等。O(n²) 深比较 —— 这里的数据都是
+       几十个以内，可读性比复杂度重要；真要上千个再换哈希。 */
+    if (schema.uniqueItems === true) {
+      for (var ui = 0; ui < data.length; ui++) {
+        for (var uj = ui + 1; uj < data.length; uj++) {
+          if (deepEqual(data[ui], data[uj])) {
+            errors.push({ path: ptr + '/' + uj,
+              msg: '第 ' + uj + ' 个元素与第 ' + ui + ' 个重复（uniqueItems）' });
+          }
+        }
+      }
+    }
     if (schema.items) {
       data.forEach(function (v, i) {
         validate(schema.items, v, root, ptr + '/' + i, errors);
@@ -228,6 +280,13 @@ function validate(schema, data, root, ptr, errors) {
       errors.push({ path: ptr, msg: '必须恰好满足 oneOf 中的一条，实际满足 ' + n + ' 条' });
     }
   }
+  /* `not`：**必须不**满足里面的约束。子校验用独立的 errors 数组 ——
+     借用外层数组的话，"不满足 not" 会被记成"满足了"的错，方向正好反了。 */
+  if (schema.not !== undefined) {
+    if (validate(schema.not, data, root, ptr, []).length === 0) {
+      errors.push({ path: ptr, msg: '不应满足 not 里的约束（实际满足了）' });
+    }
+  }
   return errors;
 }
 

package/dist/COSTS.md

@@ -18,22 +18,22 @@
 
 | 档 | 组件 | tokens（必付） | CSS | JS | **合计** | 源码版合计 | 差 |
 |---|---|---:|---:|---:|---:|---:|---:|
-| primitive | `badge` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 24.7 KB | −21.2 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.1 KB** | 28.1 KB | −24.0 KB |
 | primitive | `combobox` | 2.9 KB | 1.0 KB | 5.7 KB | **9.6 KB** | 31.8 KB | −22.2 KB |
-| primitive | `date-range` | 2.9 KB | 0.8 KB | 2.8 KB | **6.6 KB** | 28.9 KB | −22.4 KB |
-| primitive | `delta` | 2.9 KB | 0.3 KB | — | **3.2 KB** | 24.7 KB | −21.5 KB |
-| primitive | `input` | 2.9 KB | 1.0 KB | — | **4.0 KB** | 25.8 KB | −21.9 KB |
+| primitive | `date-range` | 2.9 KB | 0.8 KB | 2.8 KB | **6.6 KB** | 28.9 KB | −22.3 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.8 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.3 KB | **6.1 KB** | 29.7 KB | −23.7 KB |
+| primitive | `popover` | 2.9 KB | 0.8 KB | 2.3 KB | **6.1 KB** | 29.7 KB | −23.6 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.3 KB | **8.1 KB** | 33.1 KB | −25.0 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.3 KB | −26.5 KB |
-| primitive | `timeline` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 25.2 KB | −21.7 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.5 KB | **8.8 KB** | 39.7 KB | −30.9 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.8 KB | −22.9 KB |
@@ -42,9 +42,9 @@
 | 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.8 KB | **7.9 KB** | 39.3 KB | −31.3 KB |
-| pattern | `pagination` | 2.9 KB | 0.8 KB | 2.8 KB | **6.5 KB** | 32.8 KB | −26.3 KB |
-| pattern | `reveal` | 2.9 KB | 0.3 KB | 1.2 KB | **4.4 KB** | 26.5 KB | −22.0 KB |
+| pattern | `overlay` | 2.9 KB | 1.2 KB | 3.8 KB | **7.9 KB** | 39.2 KB | −31.3 KB |
+| pattern | `pagination` | 2.9 KB | 0.8 KB | 2.8 KB | **6.5 KB** | 32.7 KB | −26.3 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 | 2.0 KB | **5.4 KB** | 28.7 KB | −23.3 KB |

package/docs/ACCESSIBILITY.md

@@ -5,8 +5,8 @@
 
 | 项目 | 值 |
 |---|---|
-| 声明适用版本 | agentcss `0.26.0` |
-| 声明日期 | 2026-11-04 |
+| 声明适用版本 | agentcss `0.27.0` |
+| 声明日期 | 2026-11-06 |
 | 复核节奏 | 每次发版前重跑（`npm run gate` 内含全部证据） |
 | 范围 | 本库交付的 CSS / JS、全部 `demo.html`（组件页 + 图表页 + 组合页）、以及文档站生成的页面 |
 | 不在范围 | 使用者拿这些组件拼出来的业务页面（那是你的无障碍责任，不是库的） |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,116 @@
+# agentcss 是怎么组成的
+
+> 写给第一次接触这个项目的人。不需要先懂前端工程，读完能回答三个问题：
+> 这是什么、东西怎么组织、靠什么保证不出乱子。
+
+**一句话**：这是一个给手机网页用的**现成零件库**——按钮、表格、抽屉、整页版式都有，
+拿来就能用。它有三个少见的特点：
+
+- **不装任何依赖**。把这个库装进项目，你的 `node_modules` 不会多出任何别的东西。
+- **类名就是说明书**。样式全靠类名控制，不要求写初始化脚本、不绑定任何框架。
+- **专门照顾 AI 编码助手**。每个组件都有一份机器可读的"说明书"，AI 先读它再写代码，
+  写完还能用配套命令自己检查。
+
+规模：40 个组件（全部稳定可用）、约 1 MB 的 npm 包、全库样式总量锁死在 172 KB 以内。
+
+## 一张图看懂
+
+```mermaid
+flowchart TD
+    subgraph lib["组件本体 —— 依赖自上而下"]
+        direction TB
+        R["整页配方 recipes · 5 个<br/>拿来就是一页完整版式"]
+        P["组合模式 patterns · 14 个<br/>抽屉、弹层、时间线…"]
+        B["基础件 primitives · 17 个<br/>按钮、表格、下拉框…"]
+        T["设计令牌 tokens + 行为核 · 6 个<br/>颜色字号间距 + 少量交互脚本"]
+        R --> P --> B --> T
+    end
+
+    subgraph use["两种用法"]
+        H["给人：复制 demo 改内容"]
+        A["给 AI：先读机器说明书，写完自检"]
+    end
+
+    subgraph out["三个出口"]
+        NPM["npm 包"]
+        WEB["文档站（40 个组件页）"]
+        REPO["GitHub 仓库（检查系统全部公开）"]
+    end
+
+    H --> NPM
+    A --> NPM
+    NPM -.-> WEB
+    NPM -.-> REPO
+```
+
+读法：想用一个小按钮，拿 `02-primitives` 里的就行；想要一整页报表，直接拿
+`04-recipes`。上面的层会用到下面的层，反过来不会——所以拆哪儿都拆得动。
+
+## 四层组件，像盖房子
+
+| 层 | 是什么 | 打个比方 | 数量 |
+|---|---|---|---|
+| `01-tokens` | 颜色、字号、间距这些"数值表"，浅色/深色两套主题；附 6 个小交互脚本（弹窗关闭、焦点归位这类） | 调色盘和刻度尺 | 1 套 |
+| `02-primitives` | 最小的独立组件：按钮、卡片、表格、下拉框 | 砖和预制板 | 17 |
+| `03-patterns` | 需要多个组件配合的场景：抽屉、弹层、标签页、时间线 | 预制房间 | 14 |
+| `04-recipes` | 一整页的成品版式：报表页、应用外壳、财务页 | 样板房 | 5 |
+
+另有 `09-assets`（4 个独立小资产，比如图表底座），不属于这套分层，按需取用。
+
+## 目录地图
+
+| 目录 | 放什么 |
+|---|---|
+| `01-tokens/` … `04-recipes/`、`09-assets/` | 上面说的组件本体，每个组件自带可打开的 demo 页和说明 |
+| `ai/` | 给 AI 看的机器说明书（4 份 JSON）和一个命令行工具 |
+| `05-audit/` | 自动检查系统（下节讲），全部公开、任何人可以运行 |
+| `docs/` | 设计与工程文档（本文在这里） |
+| `dist/`、`esm/`、`types/` | 构建产物，由源码自动生成，不许手改 |
+
+## 修改一处，处处自动跟上
+
+这个项目最讲究的一件事：**同一份数据只存一个地方，别的都由它自动生成。**
+
+- 40 个组件的清单（类名、状态、无障碍属性）只写在 `ai/components.json` 一处。
+  文档站的 46 个页面、给 AI 的摘要文本，全部由这份清单自动生成——
+  有一个自动检查专门盯着"生成物和清单是否一致"，改了清单忘了重新生成就会红。
+- 关键数字同理：文档里写的组件数、检查数，都有自动检查对着源头核。
+
+好处很直接：文档不会和实现"各说各话"，因为大部分文档本来就是实现生成的。
+
+## 怎么保证不出乱子：一个自动验收系统
+
+仓库里有一套自动检查（这个项目里叫"门禁"），共 **251 项**，像三道验收：
+
+| 什么时候跑 | 跑多少 | 多快 | 查什么 |
+|---|---|---|---|
+| 每次提交前 | 5 项 | 约 7 秒 | 说明书、页面结构、文案、类型有没有被改坏 |
+| 每次推送时 | 128 项 | 约 3.5 分钟 | 以上全部，外加所有不需要浏览器的检查 |
+| 发布之前 | 251 项 | 约 10 分钟 | 再加真浏览器实测、逐像素视觉比对、安装包体检 |
+
+三条规矩让它长期可信：
+
+1. **每个检查先证明自己能抓到问题**——故意弄坏一个组件，检查必须变红；
+   把检查关掉后问题必须重新出现。做不到这一点的检查不算数。
+2. **"跳过"不等于"通过"**——环境缺浏览器就明确标"本次没查"，绝不悄悄变绿。
+3. **没测过就说没测**——真机只在 5 类环境验证过，其余内核明说"未验证"，不写"应该没问题"。
+
+## 给 AI 编码助手怎么用
+
+机器说明书在 `ai/` 目录，四份 JSON 覆盖：每个组件的类名与状态、已知的坑、
+设计数值、交互脚本的行为。配套命令行工具（装完这个包就能用）：
+
+```bash
+npx agentcss ai components --json        # 列出全部 40 个组件
+npx agentcss ai check page.html --json   # 检查你写出来的页面合不合规范
+npx agentcss ai shot page.html --width=390,1440   # 按真实手机宽度截图
+npx agentcss ai scaffold report/finance  # 生成一页报表的最小骨架
+```
+
+流程就是：**读说明书 → 出骨架 → 填内容 → 自己检查**。最后一步不是可选项——
+"写完了"和"写对了"是两件事。
+
+---
+
+*本文数字的出处：组件数来自 `ai/components.json`；检查项数以 `05-audit/check-all.sh`
+实际注册为准；样式预算见 `docs/BUDGET.md`。均为 2026-11-05 的实测值。*

package/docs/LAYER-BASELINE.md

@@ -34,7 +34,7 @@
 不是手抄的，也不是推测的：探针页把结果 **POST 回采集端**，落成 JSON 后原样贴进表格。
 手机访问 `http://<电脑内网地址>:端口` 属于**非安全上下文**，
 `navigator.clipboard` 在那里根本不存在 —— 所以页面提供的是"发送到电脑"（同源 POST）作为主路径，
-剪贴板只作备用（详见 `ERRORS.md` E47）。
+剪贴板只作备用。
 
 ---
 
@@ -163,7 +163,7 @@ Android 上 Chrome ≠ 系统 WebView ≠ 各家 App 内置 WebView。**入口
 
 「iOS 16.4 才支持某个特性」这类说法在本文件里没有位置，原因很直接：
 我没有在真机上验证过它，写下来就会被下一个人当成事实引用
-（`ERRORS.md` E13 记过一类同源事故：文档里的结论没人回来复核，最后整份文档都在骗人）。
+（一类同源事故：文档里的结论没人回来复核，最后整份文档都在骗人）。
 
 ⇒ 需要版本结论时，**跑一次探针页**，用那一次的 UA 与结果说话。
 UA 是证据，版本传闻不是。

package/docs/PRINT.md

@@ -291,8 +291,8 @@ L3 声明→生效 在真浏览器的 print 媒体下量标本页的计算值
 ```
 
 反向控制 7 条（覆盖四条腿），其中两条是历史事故的**逐字复刻**：
-E254（去掉 `.tabs ` 前缀，让组件 CSS 同特异性盖掉它）与
-E255（只删 `visibility: visible`，display 与高度全对、一个字不印）。
+去掉 `.tabs ` 前缀，让组件 CSS 同特异性盖掉它；以及
+只删 `visibility: visible`，display 与高度全对、一个字不印。
 
 ### 内容完整性是**硬判据**（2026-11-02 起）
 
@@ -356,7 +356,7 @@ npx agentcss pdf report.html --out report.pdf --max-pages=8
 
 `--paper` 支持 `a4` / `letter` / `a5` / `a3` / `legal`。边距是 CSS 简写
 （`18mm`、`"18mm 15mm"`、四段都认）。这两个参数靠**注入一条 `@page` 规则**实现，
-注入位置在使用者样式之后 —— 否则同特异性会被盖掉（E254 的同一个病）。
+注入位置在使用者样式之后 —— 否则同特异性会被盖掉（同一个病）。
 
 零运行时依赖：用使用者机器上**已装好的** Chrome / Chromium / Edge。
 找不到就明确报错（退出码 3），不静默降级成空文件。指定位置：

package/docs/RELEASE-PROCESS.md

@@ -132,7 +132,7 @@ pack-smoke.sh            # npm pack → 装进空项目 → 解析入口
 
 工作流按这个顺序落地：
 
-1. 校验 tag 名 == `package.json.version`，检查 `NPM_TOKEN`；
+1. 校验 tag 名 == `package.json.version`，并确认 npm 足够新（OIDC 需 ≥ 11.5.1）；
 2. `npm ci`；
 3. **probe**（只读）：输出 `npm=… release=… provenance=…`；
 4. `publish:check`；
@@ -156,7 +156,7 @@ pack-smoke.sh            # npm pack → 装进空项目 → 解析入口
 
 ⚠️ 第 8 步的回执必须**等 registry 索引**。`npm publish` 返回 0 之后，版本端点还要几十秒才可见；
 回执在发布后立刻跑，会拿到 `npm=absent` 并把一次成功的发布报成「未完成」。
-`release-run.sh verify` 现在对 `absent` 重试（默认 18 次 × 10 秒），
+`release-run.sh verify` 现在对 `absent` 重试（默认 42 次 × 10 秒 = 420 秒），
 对 `unreadable` **不重试**（那是接口/网络问题，等下去也不会变）。
 
 这条不是推演，是 `v0.24.2` 第三次运行的现场：npm 与 Release 都建好了，
@@ -164,6 +164,56 @@ pack-smoke.sh            # npm pack → 装进空项目 → 解析入口
 registry `integrity` 与 attestation `subject` 全部一致——产物是对的，
 错的是**回执比索引快**。
 
+⚠️ 预算必须**明显大于**实测最大值，不能贴着它设。`v0.26.0`（2026-11-05）是第二次：
+`npm publish` 在 `08:15:34` 返回成功，registry 到 `08:18:40` 才索引到——**186 秒**，
+而当时的上界是 `17 × 10 = 170` 秒，回执在 `08:18:38` 放弃，比真相早 2 秒。
+后果：包已经发出去了，回执却写 `npm=absent`，要再跑一遍 14 分钟的门禁才能拿到绿。
+⇒ 现在的 420 秒是实测量级的 6 倍：慢只是多等，错判是回执说谎。
+
+### 5.1.1 事后改包（dist-tag 等）：走 trusted publishing，不要走令牌
+
+发布完成后要改**包管理类**的状态（例如删一个 dist-tag），**不要**想着用发布令牌去做：
+
+- 勾了「绕过两步验证」的细粒度令牌（GAT）自 2026-07 起只能发布写，做包管理删除会被
+  `403 Granular access tokens that bypass two-factor authentication may not perform this action` 挡住；
+- npm 网页里**没有** dist-tag 管理入口（`/package/<pkg>/dist-tags` 是 404，
+  Versions 的 Current Tags 只有只读表格）；
+- 剩下唯一合法的口子是 **trusted publishing**：它的 Allowed actions 里明确有 `npm dist-tag`。
+
+本仓的落地方式（一次性运维，不影响发版）：
+
+1. npm 包设置 → Trusted Publisher → GitHub Actions，
+   仓库标识（`owner/repo`，见 `package.json` 的 `repository`）与 `release.yml`，
+   勾 `npm publish` 与 `npm dist-tag`；
+2. `release.yml` 里的 `dist-tag-cleanup` job：只在 `workflow_dispatch` 且填了
+   `dist_tag_rm` 时跑；`id-token: write` 换 OIDC 凭证；先 `npm i -g npm@latest`
+   （OIDC 需 ≥ 11.5.1）；**不要**给 `setup-node` 传 `registry-url`
+   （它会写一条空的 `_authToken` 行，值指向 `NODE_AUTH_TOKEN`，先撞 ENEEDAUTH，轮不到 OIDC）；
+3. 触发：
+
+```bash
+gh workflow run release.yml -f dist_tag_rm=<tag 名>
+```
+
+2026-11-05 实测：run 41997717147 success，`probe-2fa` 删除后只剩 `latest`。
+这条作业**不会**被 tag 推送触发（条件是 `github.event_name == 'workflow_dispatch'` 且输入非空）。
+
+### 5.1.2 发版本身的凭据：OIDC，没有任何长期令牌
+
+发版与上面的包管理动作共用同一套信任关系：npm 侧把 `release.yml` 登记为
+trusted publisher（`Status: Valid`），工作流用 `id-token: write` 现换一次短期凭证。
+**仓库里不再有任何 npm 令牌 secret**，也没有 7 天/90 天到期的东西会悄悄断掉发布。
+
+两条硬约束（都实测踩过，`release-gate.py` 的 `workflow_problems` 逐条守着）：
+
+1. `setup-node` **不传** `registry-url` —— 它会写一行空的 `_authToken`（值指向
+   `NODE_AUTH_TOKEN`），npm 先撞 `ENEEDAUTH`，根本轮不到 OIDC；
+2. 必须 `npm install -g npm@latest` —— Node 22 自带 npm 10.x，OIDC 需要 ≥ 11.5.1。
+
+`workflow_problems` 同时**反向**断言：谁把 `NPM_TOKEN` / `NODE_AUTH_TOKEN` /
+`registry-url` 加回来，门禁立刻红。这不是风格检查——长期令牌模型在 2027-01
+会连直接发布权一起失效，留着它只是把断点推迟到下一次发版。
+
 ### 5.2 站点链（主分支触发）
 
 | 态 | 含义 | 探测方式 |

package/docs/STABILITY.md

@@ -30,7 +30,7 @@
 | JS 成员不消失 | `Select.open()`、`AccordionOptions.duration` 这类名字 | `deprecation-gate.py` ⑦ + `api-contract-gate.py`（d.ts ↔ 运行时**实测**比对） |
 | 声明的名字真的存在 | 不许出现"文档里有、代码里没有"的幻觉 API | `gen-ai-contract.py --check`、`dead-class-gate.py` |
 | 行为事件名不消失 | `fl:select` 这类事件名 | 只记在基线里，**没有运行时探针**（见 §6） |
-| CLI 子命令与 `--json` 形状 | `agentcss ai <cmd> --json` 的 11 个子命令、失败也是 JSON | `ai-layer-gate.js` ⑥′⑥″ |
+| CLI 子命令与 `--json` 形状 | `agentcss ai <cmd> --json` 的 14 个子命令、失败也是 JSON | `ai-layer-gate.js` ⑥′⑥″、`facts-gate.py`（计数从 `ai/cli.js` 现算） |
 | 契约文件字段 | `ai/components.json` / `pitfalls*.json` / `behaviors.json` | `gen-ai-contract --check`、`ai-layer-gate` ⑦ |
 | 文件路径 | `02-primitives/button/button.css` 这类 `<link>` 直接指向的路径 | `dist-parity-check`、`pack-smoke.sh`、`assets-catalog-gate.py` |
 | 体积承诺 | 全库生效 CSS ≤ 172 KB，常规增长不涨价 | `perf-gate.py` + `budget-selftest.py`（见 [BUDGET.md](BUDGET.md)） |

package/docs/VERIFY-RELEASE.md

@@ -170,3 +170,20 @@ a3d36f35ee748632ba05705e669ce950260dd81a3d32b5f3f46fadae0bd084ef   # npm 包内
 ## 6. 更早的版本
 
 provenance 不是从第一个版本就有的。实测 `0.10.0` 的 attestation 接口返回 404 —— 这类版本只能核对 `gitHead`（L0），不要把它当作签名证据。
+
+---
+
+## 7. 已知偏差：2026-11-05 的历史重写
+
+| 项 | 内容 |
+|---|---|
+| 发生了什么 | 仓库提交历史被重写一次，用于移除早期版本里误留的真实项目代号与本机用户名 |
+| 受影响范围 | **`0.26.0` 及更早**的 provenance 里记录的 `gitCommit` |
+| 具体表现 | 那个 SHA 在重写后的仓库里**不再是任何分支的祖先**；`git cat-file -p <sha>` 会报 `Not a valid object` |
+| 仍然成立的部分 | npm 上的 attestation 本身**没有被改动**（sigstore 签名是不可变的）。它仍然能证明：这个 tarball 由本仓库的 `release.yml` 在某个提交上构建 |
+| 从什么时候恢复正常 | `0.27.0` 起，provenance 的 `gitCommit` 与仓库历史一致 |
+| GitHub 侧 | 旧提交会以**不可达对象**状态保留一段时间，知道 SHA 仍能按地址访问；之后由平台 GC。仓库已无任何 ref 指向它们 |
+
+核验旧版本时正确的读法：**签名证明"构建来源与工作流"，不证明"那个提交现在还在仓库里"**。
+这两件事在重写前是重合的，重写后必须分开看 —— 本文件不打算把这一点藏起来。
+

package/index.html

@@ -39,7 +39,7 @@ li a:active { background: var(--surface-sunken); }
 <li><a href="02-primitives/choice/demo.html">checkbox / radio / select</a><span class="r__p">单选/多选/原生 select 外观的统一控件</span></li>
 <li><a href="02-primitives/combobox/demo.html">combobox · 组合框 / 标签输入</a><span class="r__p">可搜索 + 可多选标签的输入控件</span></li>
 <li><a href="02-primitives/date-range/demo.html">date-range · 日期区间</a><span class="r__p">日期区间选择，含预设快捷范围</span></li>
-<li><a href="02-primitives/delta/demo.html">delta · 变化量</a><span class="r__p">变化量：涨跌方向 + 符号 + 颜色。只描述往哪边变，不判断好坏（等于好恶是 badge 的事，会计正负是 ta</span></li>
+<li><a href="02-primitives/delta/demo.html">delta · 变化量</a><span class="r__p">变化量：涨跌方向 + 符号 + 颜色。</span></li>
 <li><a href="02-primitives/input/demo.html">input / field</a><span class="r__p">文本输入及其标签/帮助/错误三件套</span></li>
 <li><a href="02-primitives/metric/demo.html">metric · 指标块</a><span class="r__p">指标块：一个标签 + 一个值 + 一句上下文。数字等宽、单位分离、缺数是一等状态</span></li>
 <li><a href="02-primitives/popover/demo.html">popover · 气泡卡片</a><span class="r__p">锚定到触发元素的浮层</span></li>
@@ -48,7 +48,7 @@ li a:active { background: var(--surface-sunken); }
 <li><a href="02-primitives/separator/demo.html">separator · 分隔线</a><span class="r__p">分隔线，可带中间文字</span></li>
 <li><a href="02-primitives/skeleton/demo.html">skeleton · 骨架屏</a><span class="r__p">加载占位骨架</span></li>
 <li><a href="02-primitives/switch/demo.html">switch · 开关</a><span class="r__p">开关切换</span></li>
-<li><a href="02-primitives/timeline/demo.html">timeline · 时间轴</a><span class="r__p">时间轴：按时间排的事件序列（公告 / 大事记 / 版本记录）。顺序即信息，用 ol；状态交给 badge，颜色在</span></li>
+<li><a href="02-primitives/timeline/demo.html">timeline · 时间轴</a><span class="r__p">时间轴：按时间排的事件序列（公告 / 大事记 / 版本记录）。</span></li>
 <li><a href="02-primitives/upload/demo.html">upload · 文件上传</a><span class="r__p">文件上传：零 JS 的原生形态 + 拖放/多文件/校验的增强形态</span></li>
 </ul>
 
@@ -97,7 +97,7 @@ li a:active { background: var(--surface-sunken); }
   </p>
 </main>
 <footer class="wrap">
-  <p class="note">0.26.0 · 零第三方运行时依赖</p>
+  <p class="note">0.27.0 · 零第三方运行时依赖</p>
 </footer>
 </body>
 </html>

package/llms-full.txt

@@ -1,6 +1,6 @@
 # agentcss — full reference (one file)
 
-> Generated from `ai/components.json` + `ai/pitfalls*.json` + `ai/behaviors.json` at version **0.26.0**.
+> Generated from `ai/components.json` + `ai/pitfalls*.json` + `ai/behaviors.json` at version **0.27.0**.
 > Do not edit by hand: run `python 05-audit/gen-llms.py` (freshness is gated).
 > Short version: `llms.txt`. Machine contract: `ai/*.json`.
 
@@ -16,10 +16,24 @@ npx agentcss ai pitfalls --json --component=table
 npx agentcss ai tokens --json --set=dark
 npx agentcss ai tree --json --set=dark --cat=color
 npx agentcss ai validate <file> --schema=components --json
-npx agentcss ai check <doc.json> --profile=strict --json
+npx agentcss ai check <doc.json> --profile=strict --json   # the plan
+npx agentcss ai check <page.html> --json                   # the artifact
+npx agentcss ai scaffold report/finance --out report.html  # skeleton only
+npx agentcss ai shot <page.html> --out shot-{width}.png --width=390,1440 --full
+npx agentcss ai pdf <page.html> --out page.pdf             # zero deps: your Chrome
 ```
 
-Every subcommand accepts `--json`; failures print `{"ok":false,...}` and exit non-zero.
+Every subcommand accepts `--json`. On failure it prints *one* JSON document —
+`{"ok":false,"command":"…","error":{"kind":"…","message":"…"}}` — so a pipeline can
+never mistake an error for data. Exit codes are one table for the whole CLI:
+`0` pass · `1` the thing you checked is bad (a verdict, not a tool failure) ·
+`2` bad flag or value (unknown flag, unknown enum value, empty value, repeated flag) ·
+`3` environment missing · `4` render failed · `5` over budget · `6` tool bug.
+`check <page.html>` is static (no network, no browser) and reports undefined class names,
+stylesheets that were never linked, missing `img alt` / table name / `th scope`, skipped
+heading levels and the per-layout obligations in `ai/recipes.json`. `shot` drives your
+installed Chrome over a debugging pipe: the viewport is exactly the width you asked for,
+and it reports horizontal overflow plus JS errors.
 
 ## 2 · Components (40)
 

package/llms.txt

@@ -21,22 +21,43 @@ npx agentcss ai tokens --json --set=dark
 npx agentcss ai pitfalls --json --component=table
 npx agentcss ai validate ai/components.json --schema=components --json
 npx agentcss ai check page.json --profile=strict --json
+npx agentcss ai check page.html --json               # check the page you actually wrote
+npx agentcss ai scaffold report/finance --out report.html   # minimal shell (skeleton, no content)
+npx agentcss ai shot page.html --out shot-{width}.png --width=390,1440 --full
+                                                    # PNG at exact viewport widths
 npx agentcss ai pdf page.html --out page.pdf --max-pages=8   # HTML → PDF (zero deps: uses your Chrome)
 ```
 
+`check <doc.json>` and `check <page.html>` answer **different** questions: the JSON one
+validates the *plan* (node kinds, component maturity, paper obligations), the HTML one
+validates the *artifact* — class names that the library does not define, stylesheets that
+were never linked, missing `img alt` / table name / `th scope`, skipped heading levels,
+and the per-layout obligations in `ai/recipes.json`. Both are static: no network, no browser.
+
+`shot` drives your installed Chrome over a debugging pipe (no port, no bundled browser) so
+the viewport is **exactly** the width you asked for, and reports horizontal overflow plus
+JS errors. Same machine + same flags ⇒ byte-identical PNG (that is what the gate checks).
+
 Print / PDF: `--medium=paper` is the obligation switch — only then are `printPolicy`
 and `pageBudget` enforced. Per-component paper behaviour lives in
 `ai/components.json` → `printPolicy`. `@page` is owned by the exporter, not the library.
 
-Every subcommand accepts `--json`. On failure it prints
-`{"ok":false,"command":"…","error":{"kind":"…","message":"…"}}` and exits non-zero,
-so a pipeline can never mistake an error for data.
+Every subcommand accepts `--json`. On failure it prints *one* JSON document —
+`{"ok":false,"command":"…","error":{"kind":"…","message":"…"}}` — and exits non-zero,
+so a pipeline can never mistake an error for data. There is exactly one failure shape;
+the `kind` values map to exit codes: `1` verdict-negative (`findings`), `2` bad usage,
+`3` environment missing, `4` render failed, `5` over budget, `6` tool bug.
+
+Enum flags (`--set`, `--cat`, `--maturity`, `--profile`, `--medium`, `--recipe`) reject
+an unknown value, an empty value, and a repeated occurrence with exit `2`. Flags a
+subcommand does not understand are rejected too — they are never silently ignored.
 
 `pitfalls` needs `agentcss@0.21.0+`: `npx` resolves the *published* version, which can lag
 this repository. If a subcommand is missing, check `npx agentcss --version` first.
 
-There is **no MCP server**: the CLI is the whole interface (read-only queries, no daemon,
-no second copy of the contract to keep in sync). See `ai/START-HERE.md` §7.
+There is **no MCP server**: the CLI is the whole interface (no daemon, no network,
+no second copy of the contract to keep in sync). `scaffold` and `shot` write only the file
+you name; every other subcommand is a read-only query. See `ai/START-HERE.md` §7.
 
 ## Use it in a page
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcss",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "移动 Web 组件库：CSS + 可选行为脚本，零第三方运行时依赖。样式用 bundler 引入，交互行为用 script 标签引入。",
   "keywords": [
     "css",
@@ -94,6 +94,7 @@
   "scripts": {
     "test": "node --test 05-audit/unit.test.mjs 05-audit/behavior-cores.test.mjs",
     "gate": "bash 05-audit/check-all.sh",
+    "gate:pre-commit": "bash 05-audit/check-all.sh --pre-commit",
     "gate:fast": "bash 05-audit/check-all.sh --fast",
     "gate:timing": "bash 05-audit/check-all.sh --timing",
     "ci:observe": "python3 05-audit/nightly-observe.py",