agentcss 0.26.0 → 0.27.1

package/01-tokens/README.md

@@ -257,7 +257,7 @@ node ai/cli.js tree   [--set=light|dark] [--cat=color]   # 第二种
    （`contrast` / `gen-ai-contract` / `gen-tokens-tree` / `token-audience` /
    `theme-sync`）。真实事故：一条 `@layer` 让六个工具同时读错，且都没有报错。
 3. 选择器是 `:root[data-market="intl"]` (0,2,0)，**不是** `:where(...)` (0) ——
-   `:where()` 抢不过 `:root` 的 (0,1,0)，写了等于没写（E135）。
+   `:where()` 抢不过 `:root` 的 (0,1,0)，写了等于没写。
 
 > 精简档（`tierA-tokens.css`）**不含**这段交换：它是一份 `<style>` 内的
 > 令牌快照，没有配套文件可引。要国际口径就自己补一条规则 ——

package/01-tokens/page.css

@@ -86,6 +86,17 @@
                   max(env(safe-area-inset-left, 0px), var(--sp-4));
 }
 
+/* 纸面视口高度不等于一屏，屏幕安全区与末尾留白也不属于正文。
+   实测长金融报告：仅去掉 padding-block-end，8 页（末页全空白）→ 7 页，
+   3689 个非空白字符保持不变；只去掉首端内边距或 min-height 都不能修它。
+   保留首端留白与左右内边距，避免顺手改变整份文档的分页位置。 */
+@media print {
+  .page {
+    min-height: 0;
+    padding-block-end: 0;
+  }
+}
+
 /* ============================================================================
    1b. 盒模型（`border-box`）—— 只在 .page 范围内生效
    ----------------------------------------------------------------------------

package/01-tokens/responsive-demo.html

@@ -76,7 +76,7 @@ p { margin: 0 0 var(--sp-4); }
   </div>
   <p style="margin-top:var(--sp-4)">
     判据很简单：<strong>这个值变了会不会导致"控件大小跟着变"？会 → 不要流体。</strong>
-    `--fs-xs` / `--fs-sm`（UI 文本）和 `--sp-1`~`--sp-3`（小间距）都属这一类。
+    <code>--fs-xs</code> / <code>--fs-sm</code>（UI 文本）和 <code>--sp-1</code>~<code>--sp-3</code>（小间距）都属这一类。
   </p>
 
   <h2>三、该用断点的：布局结构</h2>

package/01-tokens/tokens.core.css

@@ -884,7 +884,7 @@
    —— 遍历所有声明、后者覆盖前者、**不看选择器**。
    把一段**条件性**的交换规则放在这里，它们会把它当成默认值叠上去，
    于是报告里「暗色 涨」显示成绿色，而浏览器里其实是对的 —— 门禁冤枉代码，
-   比漏判更难查（实测，见 E137）。
+   比漏判更难查（实测）。
    ⇒ 本文件只放「无条件声明」与「暗色媒体段」，条件规则一律外置。
    ========================================================================= */
 

package/01-tokens/tokens.css

@@ -926,7 +926,7 @@
    —— 遍历所有声明、后者覆盖前者、**不看选择器**。
    把一段**条件性**的交换规则放在这里，它们会把它当成默认值叠上去，
    于是报告里「暗色 涨」显示成绿色，而浏览器里其实是对的 —— 门禁冤枉代码，
-   比漏判更难查（实测，见 E137）。
+   比漏判更难查（实测）。
    ⇒ 本文件只放「无条件声明」与「暗色媒体段」，条件规则一律外置。
    ========================================================================= */
 
@@ -1117,7 +1117,7 @@ input[type="submit"],
   /* ⚠️ 模态的遮罩规则**不在这里**，在 03-patterns/overlay/overlay.css。
      原因不是洁癖：`.dialog-backdrop { position: static }` 写在这里会被
      overlay.css 里同特异性的 `position: fixed` 盖掉 —— 规则写了、不生效、
-     不报错（E254 的同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
+     不报错（同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
 
   /* 不跨页切断。代价：高于半页的卡片会被整体推到下一页 ⇒ 页数可能变多。 */
   tr, img, figure, svg,

package/02-primitives/date-range/date-range.js

@@ -194,7 +194,7 @@
     }
 
     function paintSummary(s) {
-      /* 🔴 不拼 innerHTML（E299）：`s` 来自两个 <input> 的 value，
+      /* 🔴 不拼 innerHTML：`s` 来自两个 <input> 的 value，
          而 `type=date` 在 Chromium 97 旧内核会回退成文本输入 ⇒ value 可为任意串。 */
       if (!summary) return;
       summary.textContent = '';

package/02-primitives/timeline/demo.html

@@ -90,7 +90,7 @@
   </div>
   <p class="small">
     <code>timeline--compact</code> 只做两件事：条目间距从 <code>--sp-4</code> 收到
-    <code>--sp-2</code>，时间挪回标题同一行。**它不改字号** ——
+    <code>--sp-2</code>，时间挪回标题同一行。<strong>它不改字号</strong> ——
     在侧栏里把字缩小，等于承认这块内容不重要，而事实往往相反。
   </p>
 

package/03-patterns/drawer/demo.html

@@ -74,7 +74,7 @@ ul.demo-list li { margin: var(--sp-1) 0; }
           <span class="dr-bar__title">筛选</span>
           <button class="dr-tiny" type="button" tabindex="-1" aria-label="关闭">×</button>
         </div>
-      <p class="cmp__why">关闭是**独立目标**：抽屉滑进来之后，用户第一件事就是找它。24px 的叉在触屏上要瞄准，点偏了就点到了背后的内容。</p>
+      <p class="cmp__why">关闭是<strong>独立目标</strong>：抽屉滑进来之后，用户第一件事就是找它。24px 的叉在触屏上要瞄准，点偏了就点到了背后的内容。</p>
     </div>
     <div class="cmp__pane cmp__good" data-good="button.drawer__close|h|>=44">
       <h3>✅ 本库：<code>drawer__close</code> 44px</h3>

package/03-patterns/overlay/overlay.css

@@ -289,7 +289,7 @@ body[data-scroll-locked] { overflow: hidden; }
       隐藏遮罩会把弹窗里的字一起吞掉（静默截断）。实测：屏幕开着 dialog 时
       打印，遮罩是 `position: fixed; inset: 0; rgba(21,24,28,.4)`，整页 40% 黑。
    ⚠️ 必须写在这个文件里：写进 tokens.css 会被这里同特异性的 `position: fixed`
-      盖掉 —— 规则写了、不生效、不报错（E254；由 print-policy-gate L3 抓到）。
+      盖掉 —— 规则写了、不生效、不报错（由 print-policy-gate L3 抓到）。
    ========================================================================= */
 @media print {
   .dialog-backdrop {

package/03-patterns/states/states.css

@@ -137,7 +137,7 @@
        ⇒ 减少动态效果的用户照样看到闪烁的微光；
      · 与 `02-primitives/skeleton/skeleton.css` 同特异性 ⇒ 谁后加载谁定生死。
 
-   即"要不要尊重减少动态效果"取决于 CSS 顺序。与 E254 同类。
+   即"要不要尊重减少动态效果"取决于 CSS 顺序。与同类。
    ⚠️ 这里与 skeleton.css 是**两份实现**（已登记在 css-ownership.json），
       修的时候两边都要看。 */
 @media (prefers-reduced-motion: no-preference) {

package/03-patterns/tabs/tabs.css

@@ -170,3 +170,12 @@
   from { opacity: 0; }
   to   { opacity: 1; }
 }
+
+/* Ctrl+P 可能落在淡入首帧；纸不是时间线。本块必须排在动画块之后（同特异性靠顺序）。 */
+@media print {
+  .tabs__panel--enter {
+    animation: none;
+    transition: none;
+    opacity: 1;
+  }
+}

package/04-recipes/app-shell/README.md

@@ -243,7 +243,7 @@ rail 下硬塞一个 `.shell__side-label` 会被 CSS 藏掉（兜底，防止它
 
 - **❌ 侧栏 `position: fixed` + 主区 `margin-inline-start`** —— 看起来能用，但侧栏被摘出
   grid 流，主区宽度靠**手抄的数字**维持（改侧栏宽就要改两处）；`inset-inline-start`
-  与 `margin-inline-start` 只要有一处漏改，RTL 下侧栏跑到右边、主区仍在右边留白。**
+  与 `margin-inline-start` 只要有一处漏改，RTL 下侧栏跑到右边、主区仍在右边留白。
 
   正确的做法见上面「侧栏为什么是 `sticky` 而不是 `fixed`」。
 

package/04-recipes/app-shell/demo.html

@@ -48,7 +48,7 @@
 
 <h1>应用外壳 · app-shell</h1>
 <p class="lede">工具型页面的骨架：左边一列常驻导航、上面一条工具栏、右边是主区。
-它存在的理由不是"少写几个 div"，而是**两个每个人都会踩的坑** —— 见下面两节。</p>
+它存在的理由不是"少写几个 div"，而是<strong>两个每个人都会踩的坑</strong> —— 见下面两节。</p>
 
 <h2>1 · 标准三段式</h2>
 <div class="demo">

package/04-recipes/longform/content.html

@@ -934,7 +934,7 @@
    —— 遍历所有声明、后者覆盖前者、**不看选择器**。
    把一段**条件性**的交换规则放在这里，它们会把它当成默认值叠上去，
    于是报告里「暗色 涨」显示成绿色，而浏览器里其实是对的 —— 门禁冤枉代码，
-   比漏判更难查（实测，见 E137）。
+   比漏判更难查（实测）。
    ⇒ 本文件只放「无条件声明」与「暗色媒体段」，条件规则一律外置。
    ========================================================================= */
 
@@ -1125,7 +1125,7 @@ input[type="submit"],
   /* ⚠️ 模态的遮罩规则**不在这里**，在 03-patterns/overlay/overlay.css。
      原因不是洁癖：`.dialog-backdrop { position: static }` 写在这里会被
      overlay.css 里同特异性的 `position: fixed` 盖掉 —— 规则写了、不生效、
-     不报错（E254 的同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
+     不报错（同一个形状，2026-11-02 由 print-policy-gate 的 L3 抓到）。 */
 
   /* 不跨页切断。代价：高于半页的卡片会被整体推到下一页 ⇒ 页数可能变多。 */
   tr, img, figure, svg,
@@ -1460,12 +1460,12 @@ body {
 指令与数据混在一起，地址按字计。</p>
 <h2>存储器构成</h2>
 <p>不同 Block II 的分段数有差异，引用时应以具体的手册为准。</p>
-<table>
+<table aria-label="存储器构成">
 <thead>
 <tr>
-<th>区域</th>
-<th>容量</th>
-<th>用途</th>
+<th scope="col">区域</th>
+<th scope="col">容量</th>
+<th scope="col">用途</th>
 </tr>
 </thead>
 <tbody>

package/04-recipes/report/demo.html

@@ -289,8 +289,8 @@
 <!-- ======================================================================== -->
 <h2 class="rule-top">4 · 🔴 本轮明确不做（不是"还没做"，是"这一版不管"）</h2>
 <ol>
-  <li><strong>分页 PDF / 印刷分页</strong>： @page 页边距、页眉页脚、页码、跨页不断行、
-      孤行寡行控制 —— 全部不在本版范围内，需要 `@page`、实物打样与 PDF 引擎验证。
+  <li><strong>分页 PDF / 印刷分页</strong>：<code>@page</code> 页边距、页眉页脚、页码、跨页不断行、
+      孤行寡行控制 —— 全部不在本版范围内，需要 <code>@page</code>、实物打样与 PDF 引擎验证。
       CSS 里只保留了"打印时不更糟"的最小保障（隐藏边注、图表不跨撕裂）。</li>
   <li><strong>自动目录、尾注/脚注、交叉引用、参考文献样式</strong>：图/表编号用 CSS counter
       做到"写第几就显示第几"，再往上的引用图（「详见图 3」这种自动维护）不支持。</li>

package/04-recipes/table/README.md

@@ -185,7 +185,7 @@ python -m http.server 8000
 会让同一格同时受两套颜色支配，谁赢取决于选择器权重 —— 那是最难查的一类 bug。
 `table-check` 的判据 ⑬ 会挡住给 `table.css` 添 `num--up` / `num--down` 的做法。
 
-### 零值：两边都不许有符号（0.12.1 修，E145）
+### 零值：两边都不许有符号（0.12.1 修）
 
 `format: 'signed-percent'` 的正号由类名触发，而旧实现判的是 `v < 0` ⇒
 `v === 0` 落进 else 分支得到 `num--pos`，渲染成「**+0.0%**」——

package/04-recipes/table/demo.html

@@ -260,7 +260,7 @@
     /* 符号：负数总是有 −（数值语义 + 无障碍第二线索）；
        正数只有 signed-* 才带 + —— 这就是"按列语义处理"。
 
-       🔴 但符号必须**跟打印出来的数字同号**（0.12.1 修，E145）：
+       🔴 但符号必须**跟打印出来的数字同号**（0.12.1 修）：
           旧实现判的是 `v < 0`，于是 `v === 0` 掉进 else 分支拿到 `num--pos`，
           渲染成「+0.0%」—— 一个没变化的数被念成"涨了"。
           同一条错还会在**四舍五入**处复现：0.0004 在 1 位精度下打印成

package/09-assets/bar/bar.css

@@ -167,7 +167,7 @@
    这里原来有一段针对 `prefers-color-scheme: dark` 的媒体查询块，
    里面只有两条：`.bar` 的 background 与 `.bar__label` 的 stroke。
    ⚠️ 那段文字在这里**故意不照抄**：多个门禁拿这个字符串当锚点，
-      注释里出现字面量会把它们带偏（E199 踩过一次）。
+      注释里出现字面量会把它们带偏（踩过一次）。
    它做的只有一件事：把 `var()` 的**兜底值**从 #fff 换成暗色值。
    令牌在的时候（本库的正式用法）两条声明解析结果完全相同 ⇒ 纯冗余。
 

package/09-assets/model-viewer/model-viewer.js

@@ -116,7 +116,7 @@
     this.ui.appendChild(this.btn);
 
     this.hint = el('p', 'mv__hint');
-    /* 🔴 文件名来自 `src`，可能是调用方拼出来的 URL（E299）。
+    /* 🔴 文件名来自 `src`，可能是调用方拼出来的 URL。
        原来用 innerHTML 直接拼 ⇒ `<img onerror>` 这类值会被解析成节点。
        改成 textContent 组装：`<code>` 与 `<b>` 仍然存在，但文本永远只是文本。 */
     var fname = el('code', null, this.src.split('/').pop() || '—');

package/AGENTS.md

@@ -2,8 +2,10 @@
 
 - **Contract (machine-readable):** `ai/components.json` — 40 components with root class, slots, variants, states, ARIA, file paths, and **`printPolicy`** (what happens to this component on paper: `omit` / `expand` / `reveal` / `keep-together` / `allow-break`, plus a `pagination` flag). Query it; never guess class names — and never assume a component prints as it looks on screen.
 - **Known failure modes:** `ai/pitfalls.json`, or `npx agentcss ai pitfalls --json --component=<id>`.
-- **Print / PDF:** `npx agentcss ai pdf <page.html> --out page.pdf [--paper=a4|letter|a5] [--margin="18mm 15mm"] [--max-pages=N]`. `@page` belongs to the exporter, never to the library. To hold a document to paper standards use `ai check <doc.json> --medium=paper` — it then requires `pageBudget` and refuses `pagination:"server"` components.
+- **Print / PDF:** `npx agentcss ai pdf <page.html> --out page.pdf [--paper=a3|a4|a5|letter|legal] [--margin="18mm 15mm"] [--max-pages=N] [--wait-ms=800] [--ready-selector="#report-ready"]`. Wait for load + fonts; use a visible ready selector for asynchronous content. A timeout or browser failure never replaces an existing PDF. `@page` belongs to the exporter, never to the library. For paper validation use `ai check <doc.json> --medium=paper` — it requires `pageBudget` and refuses `pagination:"server"` components.
 - **Query:** `npx agentcss ai components --json [--maturity=stable]` · `ai tokens --json [--set=dark]` · `ai tree --json`.
-- **Validate:** `npx agentcss ai validate <file> --schema=components --json`. Every subcommand accepts `--json`; failures print `{"ok":false,…}` and exit non-zero.
+- **Validate, then branch on the exit code:** `npx agentcss ai validate <file> --schema=components --json`. Every subcommand accepts `--json`; failures print exactly one document `{"ok":false,"command","error":{"kind","message"}}`. Codes are one table for the whole CLI: `0` pass · `1` what you checked is bad (a verdict) · `2` bad flag or value — unknown flag, unknown enum value, empty value and a repeated flag all land here · `3` environment missing (no browser / no `node`) · `4` render failed · `5` over budget · `6` tool bug. A typo can never degrade into "empty result, exit 0".
+- **Check the page you actually wrote:** `npx agentcss ai check <page.html> [--recipe=report/finance]`. Static — no network, no browser. It reports class names the library does not define, stylesheets that were never linked (naming the file that defines the class), missing `img alt` / table name / `th scope`, skipped heading levels, and the per-layout obligations in `ai/recipes.json`. `npx agentcss ai scaffold <recipe> --out <page.html>` gives a minimal shell that already passes.
+- **See it before shipping:** `npx agentcss ai shot <page.html> --out shot-{width}.png --width=390,1440 --full`. The viewport is exactly the width you ask for (a cropped window is not the same thing), and it reports horizontal-overflow culprits plus JS errors.
 - **Markup ground truth:** each component's `demo.html`. Restyle through tokens (CSS variables); never rewrite component selectors.
 - **Docs are Chinese:** `ai/START-HERE.md` (navigation). English entry points: `README.md`, `llms.txt`, `llms-full.txt`.

package/CHANGELOG.md

@@ -12,9 +12,130 @@
 - **次版本**：新增组件 / 新增能力（下游不改代码也能升级）
 - **修订号**：修 bug、修文案（下游无需任何改动）
 
+> **关于历史条目里的 `E123` 这类编号**：那是 0.26.0 及更早版本沿用的
+> 内部失误台账索引，台账本身不随包分发。从 0.27.0 起，本文件只描述
+> **改了什么、影响谁**，不再引用内部编号 —— 读者不需要一份查不到的索引。
+
 ## [Unreleased]
 
-（无）
+## [0.27.1] - 2026-11-06
+
+### Added
+
+- **`ai pdf` 有了就绪契约：`--wait-ms`（0–60000，默认 800）与
+  `--ready-selector=<CSS>`。** 导出顺序固定为：页面 `load` → `document.fonts.ready`
+  → 可选可见元素 → 额外等待 → 固定动画终态 → `Page.printToPDF`。
+  选择器在打印媒体下必须可见且有尺寸 —— 只存在但 `display:none` 不算就绪。
+  整个导出默认 60 秒总预算，超时是明确失败（退出码 4），不是"等一下大概就好了"。
+
+### Fixed
+
+- **PDF 导出不再把旧文件当成本次成功。** 导出改走共享零依赖 CDP 管道
+  （`ai/cdp.js`，截图与 PDF 共用）。浏览器只写暂存产物，先验 `%PDF-` 文件头与页树，
+  再原子替换最终文件；浏览器失败、超时、非法参数或暂存产物无效时，已有 PDF
+  逐字节保留，结论明确为失败。未捕获 JS 异常随 `jsErrors` 返回。
+  超页数预算仍是另一种结果：保留完整的新 PDF 并返回 `over-budget`，绝不静默截断。
+- **纸张不再吞下淡入面板或单独多出空白尾页。** Tabs 在 print 媒体下取消动画／过渡
+  并让 `opacity` 落到 1；`.page` 在 print 媒体下去掉屏幕最小高度与末尾内边距。
+  真实金融长文由 8 页（两页空白）修为 7 页，且每页都有文字。新增延迟内容、旧文件哈希
+  保护、有界超时与真实长文逐页内容、崩溃结论形状与临时文件清理判据（E14–E20）。
+- **修正 AI 入口文档漂移。** 暗色查询统一为 `--set=dark`；区分 `check` 的 HTML/JSON
+  输入与 `diff` 的 JSON 输入；零模型 Benchmark 记录明确为 `3 / UNVERIFIED`。
+
+## [0.27.0] - 2026-11-06
+
+### Added
+
+- **`ai check <page.html>` —— 校验产物，而不只是计划。**
+  此前 `ai check` 只吃 `doc.json`（节点类型、组件档位），管不到"写出来的那一页"。
+  新增 16 条判据，查的都是**不会报错、只会静默失效**的东西：
+  类名库里没有 / 类名库里有但这页没引到定义它的样式表（指名到文件）/
+  引的样式表一个都读不到 / `<img>` 缺 `alt` / 表没有可访问名称 /
+  `th` 缺 `scope` / id 重复 / 标题跳级 / 表单控件没有可读名称 /
+  `target="_blank"` 缺 `rel="noopener"` / 缺 `lang`、`charset`、`viewport`。
+  纯静态：不联网、不启动浏览器。按扩展名分派，`check x.json` 的行为不变。
+- **`ai shot <page.html> --out shot-{width}.png` —— 出 PNG。**
+  用 Chrome 的调试管道（不开端口、不打包浏览器）把视口**设成**要的宽度，
+  再截图。为什么不用 `--window-size`：Windows 上窗口有最小宽度，
+  `--window-size=390` 实际按 500px 排版、只按 390 裁一刀 —— 图是好的，
+  内容不对，且不报错。输出里同时给出横向溢出（指名元素）、内容高度与 JS 报错。
+  同一台机器、同样参数两次逐字节一致（门禁验的就是这条）。
+- **`ai scaffold <版式> --out page.html` —— 三个最小壳**（`report/finance`、
+  `report/technical`、`report/magazine`）：只给正确的骨架与必有件的位置，
+  不含内容。三个壳都由门禁跑一遍 `ai check --recipe=<自己>`。
+- **`ai/recipes.json`** —— 版式"必有件"的机器可读事实：能从标记判定的写进
+  `requires`（少一件就报错），判不了的写进 `unchecked`（只打印，不判过）。
+- **`prose-gate`** —— 检查页面的**可见文本**：未渲染的 `**加粗**` / 反引号 / `](链接)`、
+  整页括号不配平（通常是把 `（…）` 切断），以及生成器是否切在语义边界上。
+  自带反向控制：四类注入必须全部抓到，注释与代码块里的同样字符不许误报。
+- **诊断可分辨**：`npm pack` 失败时 `pack-closure` 会打印 npm/node 版本、cwd、
+  stdout/stderr 尾，并区分"产品失败（package.json 坏了）"与"清单没拿到（无法判定）"；
+  `check-all.sh` 在 `node` 不在 PATH 时一次性说明并整体退出 `3`，
+  而不是让 5 道 python 门禁各抛一个 `WinError 2` 堆栈。
+
+### Changed
+
+- **退出码统一成一套，并且可以按码分支。** 以前同一个 `--profile` 写错，
+  `pdf` 给 2、其它子命令给 1；而 `1` 同时表示"页面有错"和"工具崩了"。
+  现在全 CLI 一张表：
+
+  | 码 | 含义 |
+  |---|---|
+  | 0 | 通过 |
+  | **1** | **判定不通过**（页面/文档确实有错 —— 是结论，不是工具坏了） |
+  | **2** | 用法错误（开关名、取值、重复、空值） |
+  | 3 | 环境不具备（没有浏览器 / 没有 node） |
+  | 4 | 渲染失败 |
+  | 5 | 超出预算（产物完整） |
+  | 6 | 工具内部错误 |
+
+  失败的 JSON 也统一成**一种形状**：`{"ok":false,"command","error":{"kind","message"}}`
+  （`pdf` 以前发的是顶层 `code`/`message`，调用方得写两个分支）。
+- **枚举开关的非法值一律报错，不再退化成"空结果"。** 以前：
+
+  ```
+  ai tokens --set=not-a-theme --json      → stdout 是字面量 undefined，退出码 0
+  ai tree   --set=not-a-theme --json      → 同上
+  ai components --maturity=not-a-level    → []，退出码 0
+  ```
+
+  对 Agent 这不是"没输出"，而是**错误的控制流**：它会把拼错的参数读成
+  "这个库没有 beta 组件"，然后据此写结论。现在非法值 / 空值 / 同一个开关给两次
+  / 开关后面吞掉另一个开关，全部 `2` 退出，并在 message 里列出合法取值。
+  合法取值**从数据现算**（`profiles.json` 的 `allowedMaturity`、`tokens.json` 的
+  `sets`、`tokens.tree.json` 的 `meta.categories`、`recipes.json` 的版式），
+  不在这里另抄一份。
+- **与本命令无关的开关不再被静默忽略。** `ai components --set=dark` 以前退出码 0、
+  什么都不说 —— 调用方会以为"按 dark 过滤过了"。现在每个子命令声明自己认识的开关
+  （`ai/cli.js` 的 `FLAGS` 表），不认识的给 `2`。
+- **`ai check <page.html> --profile` / `--medium` 明确报错**：这两个开关只对
+  `doc.json` 有效。以前静默忽略 ⇒ 调用方以为"按 strict 档查过了"。
+
+### Fixed
+
+- **Schema 校验器实现了 `uniqueItems` 与 `not`。** 这两个关键字一直挂在
+  "已实现"白名单里却没有实现：`validate({type:'array',uniqueItems:true},[1,1])`
+  返回 `ok:true`，`validate({type:'number',not:{const:1}},1)` 同样。
+  白名单只保证"允许出现"，不保证"真的校验" —— 现在逐个关键字都有正/负契约用例，
+  新加关键字却不写用例，门禁直接红。
+- **能力预扫从 4 份 schema 扩到全部 8 份。** 以前只扫 contract/components/tokens/patch，
+  `behaviors` / `deprecations` / `tokensAudience` / `tokensTree` 从来没被扫过 ——
+  它们里面出现未知关键字也不会有人知道。扩上去当场撞出一个真 bug：
+  `patternProperties` 的**键是正则**，被当成关键字检查，于是
+  `tokensAudience` 报"用了没实现的关键字"（schema 本身完全合法）。
+- **生成器不再按字符硬切句子。** 首页摘要以前是 `purpose[:56]`，于是
+  `delta` 结尾是「会计正负是 ta」、`timeline` 是「颜色在」，首页还因此括号不配平。
+  现在按语义边界切（句末标点 > 分句边界 > 硬切 + 省略号），并且括号必须配平。
+  `aria-label` 里的小节名走同一条规则 —— 读屏会把它逐字念出来。
+- **可见文本里不再有未渲染的 Markdown。** 修了 5 处：
+  `timeline` / `drawer` / `app-shell` 的 `**加粗**`，`responsive-demo` 与
+  `report` 页里的反引号代码；另有 `guide/app-shell.html` 的一个孤立 `**`
+  （源头是 `04-recipes/app-shell/README.md` 里一处没闭合的加粗）。
+- **`md-render.py` 产出的表格补 `scope="col"` 与可访问名称**
+  （取最近一节的小节标题作 `aria-label`）。此前每一份从 Markdown 出来的页面
+  都缺这两件 —— GFM 的表格语法里没有它们可写，而缺了不会报错，
+  只会让读屏用户听到一串没有表头的数字。
+- `04-recipes/longform/content.html` 随之重生成（差 4 行，纯属性）。
 
 ## [0.26.0] - 2026-11-04
 
@@ -141,7 +262,7 @@ F8（demo 对比度）、F10（model-viewer 小溢出）、F12（缺 SemVer/废
   按真值更正，历史段落只加注记、不改写。
 
 上述每一项都跑了正向、反向控制与真实发布包验证；发布前全量门禁 0 FAIL。
-新增的失误与纠正规则登记在内部 `ERRORS.md`（不随包分发）。
+新增的失误与纠正规则登记在内部失误台账（不随包分发）。
 
 ---
 
@@ -335,7 +456,7 @@ README 里「想知道我们踩过哪些坑」的指向，从内部文件改到
 
 ### 修复：9 处指向不存在文件的引用
 
-`ERRORS.md`（在内部目录，不入库）、`docs/ROADMAP.md`、`docs/GUIDANCE.md` 被
+内部失误台账（不入库）、`docs/ROADMAP.md`、`docs/GUIDANCE.md` 被
 README / CONTRIBUTING / 05-audit/README 引用，但文件不存在。
 现在全部改指向真实文件，或去掉编号（内部条号对外部读者没有意义）。
 
@@ -1339,7 +1460,7 @@ G0d 前提：G4 的替换真的改到了文件
 现在：
 
 - 词表统一走 `terms`（原来 outsider-audit 自己抄了一份，与 leak-scan 口径不同）
-- 真实代号与用户名模式搬进 `internal/private-terms.txt`
+- 真实代号与用户名模式移出公开树
   （`.gitignore` 里，也不在 npm `files` 里 ⇒ 不进包）
 - 读不到时**不假装扫过**：`terms.private_status()` 由三道扫描器打印
   「私有词表未加载 ⇒ 本次未覆盖」
@@ -2084,7 +2205,7 @@ Actions → release → Run workflow → 勾 `shoot_baseline`，
 ### 文档对齐
 
 - `CONTRIBUTING.md`：补「全量为什么**不**在 CI 上跑」的完整理由与责任边界；
-  补 `rc=3` 三态表；补「失败时先读 `internal/tmp/selftest-fail-*.log`」。
+  补 `rc=3` 三态表；补「失败时先读本地门禁日志」。
 - `docs/A11Y-MANUAL-PROTOCOL.md`：结果表补 `accordion` / `drawer` / `dropdown`
   三行 —— 三个 beta 组件此前一个都不在表内，而「beta 升 stable」的判据之一
   就是行为零欠账，人工读屏是唯一的用户侧证据。**状态仍写「未执行」**：

package/CONTRIBUTING.md

@@ -27,23 +27,45 @@
 npm ci                 # 按锁文件装（验证 lockfile 真能装）
 npm run gate           # 全量：含浏览器类
 npm run gate:fast      # 只跑静态层，不用装浏览器
+npm run gate:pre-commit # 提交前：五道秒级判据（实测约 7s）
 ```
 
+三档不是"快慢"的区别，是**判断边界**的区别：
+
+| 档 | 什么时候跑 | 能证明什么 |
+|---|---|---|
+| `gate:pre-commit` | 每次 `git commit` 前 | 契约 / 页面结构 / 文案 / 行为核心 / 类型没被改坏 |
+| `gate:fast` | push 前 | 加上静态层的全部判据（不含浏览器） |
+| `gate` | 收尾、发版前 | 全部，含浏览器、视觉基线、打包闭包 |
+
+`gate:pre-commit` 走绿只说明"可以提交"，**不说明可以发版**。想让它自动跑，
+把 `bash 05-audit/check-all.sh --pre-commit` 写进 `.git/hooks/pre-commit` 即可；
+本仓不替使用者装 hook —— 提交节奏是个人选择。
+
 全量的门禁条数由 `05-audit/check-all.sh` 实算，**不在文档里写死** —— 新增一道门禁
 就会变，写下来的第二天就是第二个会漂的真值（I-7）。默认 `min(核数, 6)` 路并发；
 组件层要起浏览器，还要逐张比浅色 / 暗色 / RTL 三套视觉基线（按平台分集，
 只比本平台那套）。条数、耗时、并发效率一律以**本轮门禁打印的结果**为准。
 只想确认没改坏静态契约的话用 `gate:fast`，几秒到几分钟。
 
-### 全量为什么**不**在 CI 上跑（这不是缺口，是结论）
+### CI 跑什么、不跑什么（边界，不是缺口）
 
 `.github/workflows/gate.yml` 分三层：`quick`（`MODE=fast`，静态 + 视觉）、
-`contract`（API 契约，需 Chromium）、`browsers`（nightly，三引擎矩阵）。
+`contract`（API 契约，需 Chromium）、`browsers`（三引擎矩阵）。
 **没有任何一处是 `MODE=full`**，而且不该有 —— 实测在 Linux runner 上跑全量会
 FAIL 10+ 道（字体渲染不同 ⇒ 视觉 diff 必然不一致；路径/编码不同 ⇒ 体积类误报；
 shallow clone ⇒ 依赖 git 状态的判据语义不同；浏览器版本不同 ⇒ 截图基线不匹配）。
 
 **一个长期红的 CI 比没有 CI 更糟**：大家会习惯性忽略它，真正的新问题也一起被忽略。
+
+触发面（2026-11-05 调整）：
+
+| 事件 | 跑哪些 | 为什么 |
+|---|---|---|
+| 直推 `master` | 只 `quick` | 这个仓库一直是直推，之前**完全没有 CI 保护**；quick 约 3–4 分钟，能挡住"本地没跑就推" |
+| PR | `quick` + `contract` | 合并前要契约 |
+| nightly / 手动 | 全部三个 job | 三引擎矩阵成本高，不该每次 push 都烧 |
+
 所以边界是：
 
 - **CI 负责**：跨平台可靠的那部分（静态契约、类型、API 形态、单引擎行为）
@@ -52,10 +74,29 @@ shallow clone ⇒ 依赖 git 状态的判据语义不同；浏览器版本不同
 `browsers` job 已覆盖三引擎的组件行为契约，但它**不替代**本机全量：
 它不跑视觉基线（基线按平台分集）、不跑 RTL/响应式/无障碍全量。
 
+### 私有词表（维护者；缺失时 leak 判据会变弱）
+
+`leak-scan` 的「真实代号 / 用户名」两类要靠一份**不随包分发**的词表才能生效。
+它放在 `internal/private-terms.txt`（已被 `.gitignore` 挡住，也不在 `package.json`
+的 `files` 里）。文件不在时，脚本会打印：
+
+```
+⚠️ 私有词表未加载（0 条）⇒ 真实代号 / 用户名判据**本次未覆盖**
+```
+
+**这不是通过**。本地开发把它放回去即可；CI 上因为拿不到这个文件，需要：
+
+1. GitHub 仓库 → Settings → Secrets and variables → Actions → 新建
+   `FL_PRIVATE_TERMS`，值就是词表全文（多行）；
+2. `gate.yml` 的 `quick` job 会把它写进 `internal/private-terms.txt` 再跑门禁；
+3. 没配时日志里会有一条 `::notice`，明确写着"这一类在 CI 上不覆盖"。
+
+⚠️ 不要把词表直接提交进仓库 —— 那等于把要防的东西本身公开了。
+
 ### 失败时先读哪里
 
 `selftest-all` 报红时，除屏幕上那 4 行摘要，**完整子输出会落盘**到
-`internal/tmp/selftest-fail-<脚本名>.log`（`internal/` 已被忽略，不进仓库）。
+`internal/tmp/selftest-fail-<脚本名>.log`（`internal/` 是本地忽略目录，不进仓库）。
 不可复现的红最需要这个 —— 摘要往往不够定位。
 
 只想验一条反向控制时，用 `SKIP_SELFTESTS="a.py,b.py" python3 05-audit/selftest-all.py`

package/README.md

@@ -31,6 +31,8 @@ The JS entry points (`esm/*.mjs`) are **ESM only** — `exports` has no `require
 
 - **Every demo page, one index** — https://owain323.github.io/frontend-lib/
 - **Component documentation with search** — https://owain323.github.io/frontend-lib/guide/
+- **How this project is organized** — [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+  (what each layer is, how the automated checks work — in plain language)
 
 Both are generated from `ai/components.json` and the per-component `README.md`
 files, so a page cannot quietly go missing from the index when a component is
@@ -331,10 +333,11 @@ Every component carries a contract covering focus order, keyboard operation, ARI
 
 ```bash
 npm ci
-npm run gate        # full gate run
-npm run gate:fast   # fast layer
-npm test            # unit and behaviour-core tests
-npm run dist        # rebuild dist/
+npm test                  # unit and behaviour-core tests
+npm run gate:pre-commit   # ~7s: the five checks a one-line change can break
+npm run gate:fast         # static layer, no browser needed
+npm run gate              # full run: browsers, visual baselines, pack closure
+npm run dist              # rebuild dist/
 ```
 
 ## License

package/README.zh-CN.md

@@ -15,6 +15,8 @@
 
 - **全部示例页，一个索引** —— https://owain323.github.io/frontend-lib/
 - **带搜索的组件文档** —— https://owain323.github.io/frontend-lib/guide/
+- **这个项目是怎么组成的** —— [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+  （四层组件、自动检查系统，用平话讲）
 
 两者都由 `ai/components.json` 与各组件的 `README.md` **生成**：
 新增组件时索引不会悄悄漏掉它，文档页里的每条链接都指向真实存在的文件。
@@ -419,7 +421,7 @@ python -m http.server 8000          # 在仓库根起静态服务
 
 ```bash
 python -m http.server 8000 &     # 🔴 必须先起静态服务：一部分门禁要真浏览器渲染
-bash 05-audit/check-all.sh       # 全量门禁约 130 项，本机约 8 分钟
+bash 05-audit/check-all.sh       # 全量门禁；条数以本轮输出为准，本机约 10 分钟
 ```
 
 每一项的输出是 `PASS` / `FAIL` / `SKIP`，末尾给出失败条数与退出码（全绿为 0）。
@@ -516,14 +518,15 @@ bash 05-audit/check-all.sh       # 全量门禁约 130 项，本机约 8 分钟
 
 ```bash
 node ai/cli.js components --maturity=stable   # 列出达到 stable 的组件
-node ai/cli.js tokens --mode=dark             # 列出暗色令牌
-node ai/cli.js check  doc.json                # 校验一份**契约文档**（读 JSON）
+node ai/cli.js tokens --set=dark              # 列出暗色令牌
+node ai/cli.js check  doc.json                # 校验契约计划（读 JSON）
+node ai/cli.js check  page.html               # 静态检查真实页面（读 HTML）
 node ai/cli.js diff   a.json b.json           # 两份契约文档按语义 id 比对
 ```
 
-> ⚠️ `check` / `diff` 吃的是 **JSON 契约文档**，**不解析原始 HTML**。
-> 想校验一个真实页面，请先用契约格式描述它，或直接跑 `npm run gate`
-> （那里有真浏览器，能验的是渲染结果而不是源文件文本）。
+> `check` 按计划与产物分流：JSON 查节点、组件档位和打印义务；HTML 查类名、
+> 样式表链接与页面结构。两者都是静态检查，不启动浏览器。`diff` 只吃 JSON；
+> 真浏览器的渲染回归由 `npm run gate` 负责。
 
 - `ai/components.json` / `ai/tokens.json` 由源码**生成**（`--check` 已接门禁）
   ⇒ 改了源码忘记重新生成就红。真值只有一份，不靠"记得同步"。
@@ -554,16 +557,19 @@ node ai/cli.js diff   a.json b.json           # 两份契约文档按语义 id
 ## 开发
 
 ```bash
-npm ci                 # 按锁文件安装
-npm test               # 单元测试（约 100ms）
-npm run test:types     # 类型契约：正例必过 + 反例必挂
-npm run gate:fast      # 静态检查（约 45 秒）
-npm run gate           # 全量检查（含浏览器）
+npm ci                    # 按锁文件安装
+npm test                  # 单元测试（约 1 秒）
+npm run test:types        # 类型契约：正例必过 + 反例必挂
+npm run gate:pre-commit   # 提交前档：5 道最容易被一行改动打破的判据（约 7 秒）
+npm run gate:fast         # 静态层：不装浏览器也能跑（约 3.5 分钟）
+npm run gate              # 全量：含浏览器、视觉基线与打包闭包（约 10 分钟）
 npm run ai -- check path/to/doc.json     # 机器可读契约的命令行（读 JSON 文档）
 npm run benchmark                        # 兼容性基准
 ```
 
-改代码时跑 `gate:fast` 即可；**提交前**再跑一次 `gate`。
+三档是**递进**关系，不是三选一：改代码时 `gate:pre-commit` 随手跑，
+推送前 `gate:fast`，发版前 `gate`。**提交前档绿 ≠ 可发版** ——
+它只覆盖"改一行就可能破"的那几道。
 
 类型声明在 `types/index.d.ts`。改动它之前先看 `API.md` 的「稳定程度约定」。