agentcss 0.27.0 → 0.27.1

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/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/AGENTS.md

@@ -2,7 +2,7 @@
 
 - **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, 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.

package/CHANGELOG.md

@@ -18,6 +18,29 @@
 
 ## [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
 

package/README.md

@@ -333,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

@@ -421,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）。
@@ -518,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` 已接门禁）
   ⇒ 改了源码忘记重新生成就红。真值只有一份，不靠"记得同步"。
@@ -556,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` 的「稳定程度约定」。
 

package/START-HERE.md

@@ -47,7 +47,7 @@
 | 进度条 / 环 | `02-primitives/progress/progress.css` | 228 | — | 有耗时过程要给进度就要 |
 | 浮层气泡 | `02-primitives/popover/popover.css` | 187 | **必需 345** (`popover.js`) | 要一段信息贴着触发元素浮出来就要 |
 | 日期区间 | `02-primitives/date-range/date-range.css` | 206 | **必需 332** (`date-range.js`) | 要选起止日期就要 |
-| 标签页 | `03-patterns/tabs/tabs.css` | 172 | **必需 316** (`tabs.js`) | 同层级内容切换就要 |
+| 标签页 | `03-patterns/tabs/tabs.css` | 181 | **必需 316** (`tabs.js`) | 同层级内容切换就要 |
 | 折叠面板 | `03-patterns/accordion/accordion.css` | 453 | **必需 389** (`accordion.js`) | 长表单分段就要 |
 | 动作菜单 | `03-patterns/dropdown/dropdown.css` | 135 | **必需 575** (`dropdown.js`) | 要一组动作（新建 / 导出 / 删除）就要 |
 | 文字提示 | `03-patterns/tooltip/tooltip.css` | 89 | **必需 299** (`tooltip.js`) | 图标按钮或缩写需要一句话解释就要 |

package/ai/START-HERE.md

@@ -58,7 +58,7 @@
 | 组件清单与成熟度 | `node ai/cli.js components --maturity=stable` |
 | 某个组件踩过的坑 | `node ai/cli.js pitfalls --component=<id>`（数据在 `ai/pitfalls.json`） |
 | 写文案 / 做演示 / 发页面时的坑 | `node ai/cli.js pitfalls --scope=writing`（数据在 `ai/pitfalls-writing.json`，不挂组件） |
-| 令牌名与取值 | `node ai/cli.js tokens --mode=dark`、`node ai/cli.js tree`（分层视图） |
+| 令牌名与取值 | `node ai/cli.js tokens --set=dark`、`node ai/cli.js tree`（分层视图） |
 | 组件真实长什么样 | 该组件目录下的 `demo.html` |
 | 英文一页速览 | `llms.txt` / `llms-full.txt`（发现层；本文件是中文详版） |
 | 页面怎么搭 | `04-recipes/` 下的示例；要写报告/长文就先 `node ai/cli.js scaffold list` |

package/ai/cdp.js

@@ -0,0 +1,152 @@
+/*
+ * cdp.js — 零依赖 Chrome DevTools Protocol 管道客户端。
+ *
+ * shot 与 pdf 共用这一份实现。调试走 fd 3/4，以 NUL 分隔 JSON；不开放端口，
+ * 不连接使用者的浏览器，也不引入 Puppeteer 运行时依赖。
+ */
+'use strict';
+
+var { spawn } = require('child_process');
+
+/** 启动一个隔离的 headless Chrome，并返回有界的 CDP 请求接口。 */
+function connect(chromePath, profile) {
+  var args = [
+    '--headless=new',
+    '--disable-gpu',
+    '--disable-extensions',
+    '--no-first-run',
+    '--no-default-browser-check',
+    '--hide-scrollbars',
+    '--remote-debugging-pipe',
+    '--user-data-dir=' + profile,
+    'about:blank'
+  ];
+  /* 只有明确以 root 在容器中运行时才允许调用方关闭沙箱。 */
+  if (process.env.AGENTCSS_NO_SANDBOX === '1') args.unshift('--no-sandbox');
+  var child = spawn(chromePath, args, {
+    stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
+    windowsHide: true
+  });
+
+  var buf = Buffer.alloc(0);
+  var pending = Object.create(null);
+  var waiters = [];
+  var listeners = [];
+  var nextId = 0;
+  var dead = null;
+  var stderr = '';
+
+  function failAll(err) {
+    dead = dead || err;
+    Object.keys(pending).forEach(function (k) {
+      clearTimeout(pending[k].timer);
+      pending[k].reject(dead);
+    });
+    pending = Object.create(null);
+    waiters.splice(0).forEach(function (w) {
+      clearTimeout(w.timer);
+      w.reject(dead);
+    });
+  }
+
+  var commandPipe = child.stdio[3];
+  var eventPipe = child.stdio[4];
+  if (!commandPipe || !eventPipe) {
+    failAll(new Error('无法建立 CDP 管道（Chrome 没能启动）'));
+  }
+  /* 🔴 必须有 error 监听。浏览器起不来时管道会以 EPIPE/ECONNRESET 结束，
+     而 Node 的流在没有 error 监听时**直接抛出** —— 那就成了"本工具崩了"，
+     和"这份 PDF 没导出来"是两件事，也让调用方看不到结构化结论。 */
+  if (commandPipe) commandPipe.on('error', function (e) { failAll(e); });
+  if (eventPipe) eventPipe.on('error', function (e) { failAll(e); });
+
+  function dispatch(msg) {
+    if (msg.id !== undefined && pending[msg.id]) {
+      var p = pending[msg.id];
+      delete pending[msg.id];
+      clearTimeout(p.timer);
+      if (msg.error) p.reject(new Error(p.method + '：' + (msg.error.message || JSON.stringify(msg.error))));
+      else p.resolve(msg.result);
+      return;
+    }
+    if (!msg.method) return;
+    for (var L = 0; L < listeners.length; L++) {
+      if (listeners[L].method === msg.method) listeners[L].fn(msg.params, msg.sessionId);
+    }
+    for (var i = waiters.length - 1; i >= 0; i--) {
+      var w = waiters[i];
+      if (w.method === msg.method && (!w.sessionId || w.sessionId === msg.sessionId)) {
+        waiters.splice(i, 1);
+        clearTimeout(w.timer);
+        w.resolve(msg.params);
+      }
+    }
+  }
+
+  if (eventPipe) eventPipe.on('data', function (chunk) {
+    buf = Buffer.concat([buf, chunk]);
+    var i;
+    while ((i = buf.indexOf(0)) >= 0) {
+      var raw = buf.subarray(0, i).toString('utf8');
+      buf = buf.subarray(i + 1);
+      try { dispatch(JSON.parse(raw)); } catch (e) { /* 忽略不完整的非 JSON 浏览器输出 */ }
+    }
+  });
+  child.stdio[1].on('data', function () { /* Chrome 常规 stdout 不属于协议 */ });
+  child.stdio[2].on('data', function (chunk) {
+    stderr = (stderr + chunk.toString('utf8')).slice(-4000);
+  });
+  child.on('error', function (e) { failAll(e); });
+  child.on('exit', function (code) {
+    failAll(new Error('Chrome 提前退出（退出码 ' + code + '）'));
+  });
+
+  function send(method, params, sessionId, timeoutMs) {
+    return new Promise(function (resolve, reject) {
+      if (dead) return reject(dead);
+      var id = ++nextId;
+      var limit = timeoutMs || 15000;
+      var timer = setTimeout(function () {
+        delete pending[id];
+        reject(new Error(method + ' 超时（' + limit + 'ms 没有回应）'));
+      }, limit);
+      pending[id] = { resolve: resolve, reject: reject, timer: timer, method: method };
+      try {
+        var message = { id: id, method: method, params: params || {} };
+        /* 顶层命令不能带 sessionId:null；Chrome 只接受“字段不存在”或字符串。 */
+        if (sessionId !== undefined && sessionId !== null) message.sessionId = sessionId;
+        commandPipe.write(JSON.stringify(message) + '\0');
+      } catch (e) {
+        clearTimeout(timer);
+        delete pending[id];
+        reject(e);
+      }
+    });
+  }
+
+  function waitEvent(method, sessionId, timeoutMs) {
+    return new Promise(function (resolve, reject) {
+      var limit = timeoutMs || 15000;
+      var timer = setTimeout(function () {
+        var at = waiters.findIndex(function (w) {
+          return w.method === method && w.sessionId === sessionId;
+        });
+        if (at >= 0) waiters.splice(at, 1);
+        reject(new Error('等 ' + method + ' 超时（' + limit + 'ms）'));
+      }, limit);
+      waiters.push({ method: method, sessionId: sessionId,
+        resolve: resolve, reject: reject, timer: timer });
+    });
+  }
+
+  return {
+    send: send,
+    waitEvent: waitEvent,
+    on: function (method, fn) { listeners.push({ method: method, fn: fn }); },
+    close: function () { try { child.kill(); } catch (e) { /* 已退出 */ } },
+    stderr: function () { return stderr; },
+    child: child
+  };
+}
+
+module.exports = { connect: connect };

package/ai/cli.js

@@ -907,7 +907,7 @@ function cmdPdf(args) {
   if (!src) {
     bad('用法：agentcss pdf <页面.html|URL> --out <file.pdf> '
       + '[--paper=a4|letter|a5|a3|legal] [--margin="18mm 15mm"] '
-      + '[--max-pages=N] [--chrome=<path>] [--json]');
+      + '[--max-pages=N] [--wait-ms=800] [--ready-selector=<CSS>] [--chrome=<path>] [--json]');
   }
   var remote = /^https?:\/\//i.test(src);
   var outFile = flag('out', null);
@@ -923,6 +923,13 @@ function cmdPdf(args) {
   if (budget !== null && !/^\d+$/.test(String(budget))) {
     bad('--max-pages 必须是 ≥1 的整数，收到 ' + JSON.stringify(String(budget)));
   }
+  var waitRaw = flag('wait-ms', null);
+  if (waitRaw === true) bad('--wait-ms 后面要跟 0–60000 的整数毫秒');
+  if (typeof waitRaw === 'string' && !/^\d+$/.test(waitRaw)) {
+    bad('--wait-ms 必须是 0–60000 的整数，收到 ' + JSON.stringify(waitRaw));
+  }
+  var ready = flag('ready-selector', null);
+  if (ready === true || ready === '') bad('--ready-selector 必须是非空 CSS 选择器');
   var chrome = flag('chrome', null);
   if (chrome === true) bad('--chrome 后面要跟可执行文件路径');
 
@@ -932,6 +939,8 @@ function cmdPdf(args) {
     paper: flag('paper', pdfExport.DEFAULT_PAPER),
     margin: flag('margin', pdfExport.DEFAULT_MARGIN),
     budget: budget === null ? null : Number(budget),
+    waitMs: waitRaw === null ? undefined : Number(waitRaw),
+    readySelector: ready,
     chrome: chrome
   });
 
@@ -951,6 +960,9 @@ function cmdPdf(args) {
     bytes: r.bytes || null,
     injected: r.injected === undefined ? null : r.injected,
     chrome: r.chrome || null,
+    waitMs: r.waitMs === undefined ? null : r.waitMs,
+    readySelector: r.readySelector || null,
+    jsErrors: r.jsErrors || [],
     ms: r.ms || null
   };
   if (!r.ok) {
@@ -973,6 +985,11 @@ function cmdPdf(args) {
   process.stdout.write('      ' + r.pages + ' 页 · ' + report.paperSize + ' · '
     + (r.margin ? '边距 ' + r.margin : '边距由页面决定')
     + ' · ' + r.bytes + ' 字节 · ' + r.ms + ' ms\n');
+  process.stdout.write('      就绪：加载与字体完成 + 额外等待 ' + r.waitMs + ' ms'
+    + (r.readySelector ? ' + 可见元素 ' + r.readySelector : '') + '\n');
+  if (r.jsErrors && r.jsErrors.length) {
+    process.stdout.write('      ⚠️ 页面有 ' + r.jsErrors.length + ' 条未捕获 JS 异常，请核对内容\n');
+  }
   process.stdout.write('      预算 ' + (r.budget === null ? '未设（无界）' : r.budget + ' 页')
     + ' · ' + (r.injected
       ? '纸幅 ' + r.paper
@@ -1178,7 +1195,7 @@ var FLAGS = {
   profile: [],
   capabilities: [],
   pitfalls: ['component', 'scope', 'tag'],
-  pdf: ['out', 'paper', 'margin', 'max-pages', 'chrome'],
+  pdf: ['out', 'paper', 'margin', 'max-pages', 'wait-ms', 'ready-selector', 'chrome'],
   scaffold: ['out', 'css-prefix'],
   shot: ['out', 'width', 'height', 'full', 'scale', 'wait', 'chrome']
 };
@@ -1231,8 +1248,9 @@ function usage() {
       '  ai profile      [--json]   列出三档及其差异\n' +
       '  ai capabilities [--json]   列出可协商的能力\n' +
       '  ai pdf          <页面.html|URL> --out <file.pdf> [--paper=a4|letter|a5|a3|legal]\n' +
-      '                  [--margin="18mm 15mm"] [--max-pages=N] [--chrome=<path>] [--json]\n' +
-      '                  HTML → PDF。零依赖（用你机器上已装的 Chrome），@page 由导出方给。\n' +
+      '                  [--margin="18mm 15mm"] [--max-pages=N] [--wait-ms=800]\n' +
+      '                  [--ready-selector=<CSS>] [--chrome=<path>] [--json]\n' +
+      '                  等加载、字体与就绪元素后导出；失败不改写旧 PDF。零依赖，@page 由导出方给。\n' +
       '  ai scaffold     <版式> --out <page.html> [--css-prefix=<前缀>] [--json]\n' +
       '                  生成最小壳（正确的骨架 + 必有件位置），不含内容。`list` 看有哪些版式。\n' +
       '  ai shot         <页面.html|URL> --out <shot-{width}.png> [--width=390,1440] [--height=900]\n' +

package/ai/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "generatedBy": "05-audit/gen-ai-contract.py",
-  "libraryVersion": "0.27.0",
+  "libraryVersion": "0.27.1",
   "$comment": "机器可读的组件契约。slots = BEM 元素名（在本库里元素名就是插槽名），states.enum = 组件会在 DOM 上写出的 data-* 取值，states.legacyClass = 仍未收敛到 data 属性的历史状态类（INVARIANT I-8 未达标）。printPolicy = 这个组件在纸上会发生什么（空数组 = 原样保留）；pagination = 内容是否被分页裁过（server 不许与 expand 同时出现，否则展开的只是当前一页）。",
   "maturityCriteria": {
     "alpha": "缺 demo.html 或缺 05-audit 下的专属门禁 ⇒ 还没被机器验证过，不要用",

package/ai/pdf-renderer.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/*
+ * pdf-renderer.js — exportPdf 的异步子进程；不是公共 CLI。
+ * 从 stdin 接收一份 JSON 配置，从 stdout 返回一份 JSON 结论。
+ * 浏览器只写工作目录里的暂存 PDF，绝不接触调用方的最终输出路径。
+ */
+'use strict';
+
+var fs = require('fs');
+var cdp = require('./cdp.js');
+
+var DEFAULT_WAIT = 800;
+var READY_INTERVAL = 50;
+
+function sleep(ms) { return new Promise(function (r) { setTimeout(r, ms); }); }
+function timeoutError(message) {
+  var e = new Error(message);
+  e.code = 'timeout';
+  return e;
+}
+
+/* 在 print 媒体下等待一个可见元素。元素只是存在但 display:none 不算就绪。 */
+function readyExpression(selector) {
+  return '(function(){try{var e=document.querySelector(' + JSON.stringify(selector) + ');'
+    + 'if(!e)return {ok:true,ready:false};var s=getComputedStyle(e);'
+    + 'return {ok:true,ready:s.display!=="none"&&s.visibility!=="hidden"&&e.getClientRects().length>0};'
+    + '}catch(e){return {ok:false,error:String(e)}}})()';
+}
+
+async function render(o) {
+  var started = Date.now();
+  var budget = o.timeoutMs || 60000;
+  var deadline = started + budget;
+  function left() { return Math.max(1, deadline - Date.now()); }
+  function checkTime(what) {
+    if (Date.now() >= deadline) throw timeoutError(what + '超出时间预算 ' + budget + 'ms');
+  }
+
+  var browser = cdp.connect(o.chrome, o.profile);
+  var jsErrors = [];
+  var timedOut = false;
+  var timer = setTimeout(function () {
+    timedOut = true;
+    browser.close();
+  }, budget);
+
+  try {
+    var target = await browser.send('Target.createTarget', { url: 'about:blank' }, null, left());
+    var attached = await browser.send('Target.attachToTarget', {
+      targetId: target.targetId, flatten: true
+    }, null, left());
+    var sid = attached.sessionId;
+    await browser.send('Page.enable', {}, sid, left());
+    await browser.send('Runtime.enable', {}, sid, left());
+    browser.on('Runtime.exceptionThrown', function (p) {
+      if (jsErrors.length >= 20) return;
+      var d = (p && p.exceptionDetails) || {};
+      jsErrors.push(String((d.exception && d.exception.description) || d.text || '未捕获异常').split('\n')[0]);
+    });
+
+    var loaded = browser.waitEvent('Page.loadEventFired', sid, left());
+    var nav = await browser.send('Page.navigate', { url: o.target }, sid, left());
+    if (nav && nav.errorText) {
+      var loadError = new Error('页面加载失败（' + nav.errorText + '）：' + o.src);
+      loadError.code = 'render';
+      throw loadError;
+    }
+    await loaded;
+    checkTime('页面加载');
+
+    /* 先固定打印环境，再判断 ready：print-only 元素也能作为就绪标志。 */
+    await browser.send('Emulation.setEmulatedMedia', {
+      media: 'print',
+      features: [{ name: 'prefers-reduced-motion', value: 'reduce' }]
+    }, sid, left());
+    var fonts = await browser.send('Runtime.evaluate', {
+      expression: 'document.fonts&&document.fonts.ready?document.fonts.ready.then(function(){return true}):true',
+      awaitPromise: true, returnByValue: true
+    }, sid, left());
+    if (fonts.exceptionDetails) {
+      throw new Error('等待字体失败：' + (fonts.exceptionDetails.text || 'document.fonts.ready rejected'));
+    }
+    checkTime('字体加载');
+
+    if (o.readySelector !== null && o.readySelector !== undefined) {
+      for (;;) {
+        checkTime('等待 ready-selector ' + JSON.stringify(o.readySelector));
+        var ready = await browser.send('Runtime.evaluate', {
+          expression: readyExpression(o.readySelector), returnByValue: true
+        }, sid, left());
+        if (!ready.result || !ready.result.value || !ready.result.value.ok) {
+          var invalid = new Error('--ready-selector 不是合法 CSS 选择器：' + o.readySelector);
+          invalid.code = 'usage';
+          throw invalid;
+        }
+        if (ready.result.value.ready) break;
+        await sleep(Math.min(READY_INTERVAL, left()));
+      }
+    }
+
+    var waitMs = o.waitMs === undefined ? DEFAULT_WAIT : o.waitMs;
+    if (waitMs) {
+      var room = left();
+      /* 剩余预算装不下这次等待时，先耗尽它再报 timeout —— 这样报错里的
+         "等的是什么 / 还剩多少"和实际发生的事一致，而不是只睡一半就下结论。 */
+      if (waitMs > room) {
+        await sleep(room);
+        throw timeoutError('额外等待 ' + waitMs + 'ms 超出剩余预算 ' + room + 'ms');
+      }
+      await sleep(waitMs);
+    }
+
+    /* 有限动画落到终态，无限动画取消；同时关掉打印过渡，避免首帧 opacity:0。 */
+    var animations = await browser.send('Runtime.evaluate', {
+      expression: '(function(){var n=0;document.getAnimations().forEach(function(a){try{'
+        + 'var t=a.effect&&a.effect.getComputedTiming?a.effect.getComputedTiming():null;'
+        + 'if(t&&isFinite(t.iterations)){a.finish()}else{a.cancel()}n++}catch(e){try{a.cancel()}catch(_){}}});'
+        + 'var s=document.createElement("style");s.setAttribute("data-agentcss-print-motion","");'
+        + 's.textContent="@media print{*,*::before,*::after{transition:none!important}}";'
+        + 'document.head.appendChild(s);return n})()',
+      returnByValue: true
+    }, sid, left());
+    if (animations.exceptionDetails) throw new Error('固定打印动画失败');
+
+    var printed = await browser.send('Page.printToPDF', {
+      printBackground: true,
+      preferCSSPageSize: true,
+      displayHeaderFooter: false,
+      marginTop: 0, marginBottom: 0, marginLeft: 0, marginRight: 0
+    }, sid, left());
+    checkTime('PDF 生成');
+    var buf = Buffer.from(printed.data || '', 'base64');
+    if (buf.length < 5 || buf.subarray(0, 5).toString('latin1') !== '%PDF-') {
+      throw new Error('浏览器返回的不是 PDF（' + buf.length + ' 字节）');
+    }
+    fs.writeFileSync(o.stagedPdf, buf);
+    return {
+      ok: true, stagedPdf: o.stagedPdf, bytes: buf.length, jsErrors: jsErrors,
+      waitMs: waitMs, readySelector: o.readySelector || null,
+      animations: animations.result ? animations.result.value : null,
+      ms: Date.now() - started
+    };
+  } catch (e) {
+    return {
+      ok: false, code: timedOut ? 'timeout' : (e.code === 'usage' || e.code === 'timeout' ? e.code : 'render'),
+      message: timedOut ? 'PDF 导出超出时间预算 ' + budget + 'ms（页面加载、字体或 ready-selector 未完成）'
+        : String(e && e.message || e),
+      jsErrors: jsErrors, ms: Date.now() - started,
+      stderr: browser.stderr().slice(-800)
+    };
+  } finally {
+    clearTimeout(timer);
+    browser.close();
+    /* Windows 上 Chrome 刚退出时仍可能持有 profile 文件句柄。 */
+    await sleep(150);
+    try { fs.rmSync(o.profile, { recursive: true, force: true, maxRetries: 3 }); }
+    catch (e) { /* 父进程还会清理整个暂存目录 */ }
+  }
+}
+
+var input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', function (s) { input += s; });
+process.stdin.on('end', function () {
+  var config;
+  try { config = JSON.parse(input); }
+  catch (e) {
+    process.stdout.write(JSON.stringify({ ok: false, code: 'render', message: '导出子进程收到非法配置' }));
+    return;
+  }
+  render(config).then(function (result) {
+    process.stdout.write(JSON.stringify(result));
+  }).catch(function (e) {
+    process.stdout.write(JSON.stringify({ ok: false, code: 'render',
+      message: String(e && e.message || e) }));
+  });
+});

package/ai/pdf.js

@@ -16,14 +16,14 @@
  * 所以它只能由"产出这份文件的人"给 —— 这正是本文件存在的理由。
  *
  * ============================================================================
- * 🔴 为什么用 Chrome 的命令行，而不是 puppeteer
+ * 🔴 为什么走共享 CDP 管道，而不是 Puppeteer 或 Chrome 一次性命令行
  * ============================================================================
- * 本库的承诺是**零运行时依赖**（package.json 里 dependencies 是空的）。
- * 为了一个"5% 的人才会用"的导出功能塞一个 ~300 MB 的浏览器包，
- * 等于让 95% 的人为 5% 的人付安装代价 —— 那是这条承诺唯一的实质内容。
+ * 本库保持**零运行时依赖**，使用机器上已装好的 Chrome/Chromium/Edge。
+ * `cdp.js` 复用截图已有的调试管道：能等加载、字体和指定元素，再 printToPDF。
+ * 一次性 `--print-to-pdf` 无法表达就绪条件，也无法可靠区分新旧产物。
  *
- * 所以：`--print-to-pdf` 走使用者**已经装好的** Chrome/Chromium/Edge。
- * 找不到就**明确报错**（`no-chrome`），绝不静默降级成一个空文件。
+ * 浏览器只写同目录暂存文件；确认本次成功后才原子替换最终 PDF。任何失败都
+ * 明确返回错误并保留旧文件，绝不把上一次产物当成本次成功。
  *
  * ============================================================================
  * ⚠️ 一条必须写下来的观测差异
@@ -202,6 +202,26 @@ function paperSpec(name) {
   return PAPERS[k] ? { key: k, ...PAPERS[k] } : null;
 }
 
+/* 硬杀（Ctrl+C / 断电 / 被任务管理器结束）会留下 `.agentcss-print-*.html`：
+   finally 没机会跑。下次导出前顺手清掉**同目录**里超过 6 小时的残留。
+   门槛设长是为了不碰另一个正在导出的进程留下的文件（单次导出是秒级）。 */
+const STALE_TMP_MS = 6 * 3600 * 1000;
+
+function sweepStaleTemplates(dir) {
+  let names;
+  try { names = fs.readdirSync(dir); } catch (e) { return 0; }
+  var removed = 0;
+  const cutoff = Date.now() - STALE_TMP_MS;
+  for (const n of names) {
+    if (!/^\.agentcss-print-.*\.html$/.test(n)) continue;
+    const p = path.join(dir, n);
+    try {
+      if (fs.statSync(p).mtimeMs < cutoff) { fs.unlinkSync(p); removed += 1; }
+    } catch (e) { /* 别处正在用 / 已删 */ }
+  }
+  return removed;
+}
+
 /** 注入到 `<head>` 末尾（**必须在使用者样式之后**，否则同特异性被覆盖）。 */
 function injectSheet(html, css) {
   const style = '<style id="agentcss-paper" data-agentcss="paper">' + css + '</style>';
@@ -230,7 +250,9 @@ function isRemote(src) {
  * @param {string} [o.margin]       CSS margin 简写（默认 18mm 15mm）
  * @param {number} [o.budget]       页数上限；超了返回 over-budget
  * @param {string} [o.chrome]       Chrome 可执行文件
- * @param {number} [o.timeoutMs]
+ * @param {number} [o.waitMs]       就绪后的额外等待，0–60000（默认 800）
+ * @param {string} [o.readySelector] 等待一个打印媒体下可见的 CSS 元素
+ * @param {number} [o.timeoutMs]    总预算，1000–600000（默认 60000）
  * @returns {object} `{ok:true, ...}` 或 `{ok:false, code, message, ...}`
  */
 function exportPdf(o) {
@@ -254,107 +276,129 @@ function exportPdf(o) {
   if (o.budget !== undefined && o.budget !== null) {
     const b = Number(o.budget);
     if (!Number.isInteger(b) || b < 1) {
-      /* ⚠️ 用 String() 而不是 JSON.stringify：`JSON.stringify(NaN)` 是 `"null"`，
-         于是 `--max-pages=abc` 会报「收到 null」—— 使用者据这句话会去查一个
-         根本不存在的 null（实测踩过）。 */
       return { ok: false, code: 'usage',
         message: '--max-pages 必须是 ≥1 的整数，收到 ' + String(o.budget) };
     }
   }
+  const waitMs = o.waitMs === undefined ? 800 : Number(o.waitMs);
+  if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 60000) {
+    return { ok: false, code: 'usage',
+      message: '--wait-ms 必须是 0–60000 的整数，收到 ' + String(o.waitMs) };
+  }
+  if (o.readySelector !== undefined && o.readySelector !== null
+      && (typeof o.readySelector !== 'string' || !o.readySelector.trim())) {
+    return { ok: false, code: 'usage', message: '--ready-selector 必须是非空 CSS 选择器' };
+  }
+  const timeoutMs = o.timeoutMs === undefined ? 60000 : Number(o.timeoutMs);
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000) {
+    return { ok: false, code: 'usage', message: 'timeoutMs 必须是 1000–600000 的整数' };
+  }
 
   const chrome = resolveChrome(o.chrome);
   if (chrome.error) return { ok: false, code: 'no-chrome', message: chrome.error };
 
   const outAbs = path.resolve(o.out);
   fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+  const staging = fs.mkdtempSync(path.join(path.dirname(outAbs), '.agentcss-pdf-'));
+  const profile = path.join(staging, 'profile');
+  fs.mkdirSync(profile);
+  const stagedPdf = path.join(staging, 'output.pdf');
 
   /* 本地文件才注入 @page：远程页面我们拿不到它的字节，硬注入等于假装改了它。 */
   let target = o.src;
   let tmpHtml = null;
-  if (!isRemote(o.src)) {
-    const srcAbs = path.resolve(o.src);
-    if (!fs.existsSync(srcAbs)) {
-      return { ok: false, code: 'usage', message: '找不到输入文件：' + srcAbs };
+  let rendered = null;
+  let buf = null;
+  let info = null;
+  try {
+    if (!isRemote(o.src)) {
+      const srcAbs = path.resolve(o.src);
+      if (!fs.existsSync(srcAbs)) {
+        return { ok: false, code: 'usage', message: '找不到输入文件：' + srcAbs };
+      }
+      const html = fs.readFileSync(srcAbs, 'utf8');
+      sweepStaleTemplates(path.dirname(srcAbs));
+      /* 与输入同目录，页面里的相对样式、字体和图片才不会失效。 */
+      tmpHtml = path.join(path.dirname(srcAbs),
+        '.agentcss-print-' + process.pid + '-' + Date.now().toString(36) + '.html');
+      fs.writeFileSync(tmpHtml, injectSheet(html, cssFor(spec, margin)), 'utf8');
+      target = pathToFileURL(tmpHtml).href;
     }
-    const html = fs.readFileSync(srcAbs, 'utf8');
-    /* ⚠️ 临时文件必须落在**同一个目录**：换成系统临时目录，页面里的
-       `./tokens.css` / `/02-primitives/...` 会全部 404，而产物看起来"只是没样式"。 */
-    tmpHtml = path.join(path.dirname(srcAbs),
-      '.agentcss-print-' + process.pid + '-' + Date.now().toString(36) + '.html');
-    fs.writeFileSync(tmpHtml, injectSheet(html, cssFor(spec, margin)), 'utf8');
-    target = pathToFileURL(tmpHtml).href;
-  }
-
-  const profile = fs.mkdtempSync(path.join(os.tmpdir(), 'agentcss-chrome-'));
-  const args = [
-    '--headless=new',
-    '--disable-gpu',
-    '--disable-extensions',
-    '--no-first-run',
-    '--no-default-browser-check',
-    /* 每次一个新 profile：使用者可能正开着 Chrome，共用 profile 会抢锁 */
-    '--user-data-dir=' + profile,
-    /* 页眉页脚（日期 / 标题 / 1/2）默认是开的，必须显式关掉 */
-    '--no-pdf-header-footer',
-    '--print-to-pdf-no-header',
-    '--print-to-pdf=' + outAbs,
-    target,
-  ];
-  /* 容器里以 root 跑才需要关沙箱 —— 默认不开，也不替使用者决定 */
-  if (process.env.AGENTCSS_NO_SANDBOX === '1') args.unshift('--no-sandbox');
 
-  let res;
-  try {
-    res = spawnSync(chrome.path, args, {
-      timeout: o.timeoutMs || 60000,
-      encoding: 'utf8',
-      windowsHide: true,
-      stdio: ['ignore', 'pipe', 'pipe'],
+    /* 公共 API 保持同步；异步 CDP 只在独立 Node 子进程中运行。 */
+    const res = spawnSync(process.execPath, [path.join(__dirname, 'pdf-renderer.js')], {
+      input: JSON.stringify({
+        src: o.src, target: target, chrome: chrome.path, profile: profile,
+        stagedPdf: stagedPdf, waitMs: waitMs,
+        readySelector: o.readySelector === undefined ? null : o.readySelector,
+        timeoutMs: timeoutMs,
+      }),
+      timeout: timeoutMs + 10000,
+      encoding: 'utf8', windowsHide: true, maxBuffer: 1024 * 1024,
+      stdio: ['pipe', 'pipe', 'pipe'],
     });
+    if (res.error && res.error.code === 'ETIMEDOUT') {
+      return { ok: false, code: 'timeout', out: outAbs, ms: Date.now() - t0,
+        message: 'PDF 导出子进程没有按时退出；最终文件未被改写' };
+    }
+    if (res.error || res.status !== 0) {
+      return { ok: false, code: 'render', out: outAbs, ms: Date.now() - t0,
+        message: 'PDF 导出子进程失败：' + String(res.error || ('退出码 ' + res.status))
+          + (res.stderr ? '\n  ' + String(res.stderr).slice(-800) : '') };
+    }
+    try { rendered = JSON.parse(res.stdout); } catch (e) { /* 下方按工具失败处理 */ }
+    if (!rendered) {
+      return { ok: false, code: 'render', out: outAbs, ms: Date.now() - t0,
+        message: 'PDF 导出子进程没有返回合法结果；最终文件未被改写' };
+    }
+    if (!rendered.ok) {
+      /* 子进程的 stagedPdf 在 finally 里已被删掉 —— 不要把它交出去，
+         否则调用方会拿到一个"看着像产物、其实不存在"的路径。 */
+      const { stagedPdf: _staged, ...rest } = rendered;
+      return { ...rest, out: outAbs, chrome: chrome.path, ms: Date.now() - t0 };
+    }
+    if (!fs.existsSync(stagedPdf)) {
+      return { ok: false, code: 'render', out: outAbs, chrome: chrome.path, ms: Date.now() - t0,
+        message: '浏览器报告成功但没有生成本次暂存 PDF；最终文件未被改写' };
+    }
+
+    /* 文件头与页树都先在暂存文件上验证，通过后才接触最终路径。 */
+    buf = fs.readFileSync(stagedPdf);
+    if (buf.length < 5 || buf.slice(0, 5).toString('latin1') !== '%PDF-') {
+      return { ok: false, code: 'render', out: outAbs, chrome: chrome.path, ms: Date.now() - t0,
+        message: '本次暂存产物不是 PDF（' + buf.length + ' 字节）；最终文件未被改写' };
+    }
+    info = pages.inspect(buf);
+    if (info.pages < 1) {
+      return { ok: false, code: 'unreadable', out: outAbs, chrome: chrome.path, ms: Date.now() - t0,
+        message: '暂存 PDF 没有可读页对象；最终文件未被改写' };
+    }
+    try { fs.renameSync(stagedPdf, outAbs); } catch (e) {
+      return { ok: false, code: 'render', out: outAbs, chrome: chrome.path, ms: Date.now() - t0,
+        message: '新 PDF 已生成，但无法替换输出文件：' + e.message + '。旧文件未被主动改写' };
+    }
   } finally {
-    /* 清理必须**同步**做完：CLI 随后就 process.exit，挂一个 setTimeout
-       等于每次导出都在系统临时目录里留一个 Chrome profile（实测漏了 6 个才发现）。
-       删不掉不算错（Windows 上偶发 EBUSY），但不能因为删不掉就不删。 */
     if (tmpHtml) { try { fs.unlinkSync(tmpHtml); } catch (e) { /* 已删 */ } }
-    try { fs.rmSync(profile, { recursive: true, force: true, maxRetries: 3 }); }
-    catch (e) { /* 交给系统清理 */ }
-  }
-
-  const ms = Date.now() - t0;
-  const stderr = String((res && res.stderr) || '').slice(-800);
-  if (res && res.error && res.error.code === 'ETIMEDOUT') {
-    return { ok: false, code: 'timeout', message: 'Chrome 在 '
-      + Math.round((o.timeoutMs || 60000) / 1000) + 's 内没有结束（页面可能有死循环或等待网络）', ms };
-  }
-  if (!fs.existsSync(outAbs)) {
-    return { ok: false, code: 'render', ms,
-      message: 'Chrome 没有产出文件（退出码 ' + (res ? res.status : '?') + '）'
-        + (stderr ? '\n  ' + stderr.trim().split('\n').slice(-4).join('\n  ') : '') };
+    try { fs.rmSync(staging, { recursive: true, force: true, maxRetries: 3 }); }
+    catch (e) { /* Windows 偶发 EBUSY，交给系统清理 */ }
   }
-
-  const buf = fs.readFileSync(outAbs);
-  if (buf.length < 5 || buf.slice(0, 5).toString('latin1') !== '%PDF-') {
-    return { ok: false, code: 'render',
-      message: '产出的文件不是 PDF（' + buf.length + ' 字节）—— 通常是页面加载失败', ms };
-  }
-
-  const info = pages.inspect(buf);
   const injected = !isRemote(o.src);
   const base = {
-    out: outAbs, bytes: buf.length, pdf: buf, ms,
-    /* 远程页面没注入 @page ⇒ `paper` 只能是 null：报 "a4" 是在陈述一个
-       没有发生的事实（实测远程导出是 612×792）。真实纸幅看 `mediaBox`。 */
+    out: outAbs, bytes: buf.length, pdf: buf, ms: Date.now() - t0,
     paper: injected ? spec.key : null,
     margin: injected ? margin : null, chrome: chrome.path,
     pages: info.pages, mediaBox: info.mediaBox,
-    injected: injected,
+    injected: injected, waitMs: waitMs,
+    readySelector: o.readySelector || null,
+    jsErrors: rendered.jsErrors || [],
   };
 
-  /* 页数两套说法不一致 ⇒ 不判预算，也不假装通过 */
-  if (!info.agree && o.budget !== undefined && o.budget !== null) {
+  /* 两套读法不一致时，连"这份 PDF 有几页"都不可信 —— 无论有没有预算。
+     只在设了预算时才检查，会让"没设预算"的调用方拿到一个可能是错页数的 ok:true。 */
+  if (!info.agree) {
     return { ...base, ok: false, code: 'unreadable',
       message: 'PDF 里 `/Type /Page` 数出 ' + info.pages + ' 页、页树 `/Count` 说 '
-        + info.countFromTree + ' 页 —— 两套说法不一致，无法判定预算' };
+        + info.countFromTree + ' 页 —— 两套说法不一致，页数不可信' };
   }
 
   if (o.budget !== undefined && o.budget !== null && info.pages > o.budget) {
@@ -393,4 +437,5 @@ module.exports = {
   /* 只为可测性导出：浏览器发现逻辑必须在"没有系统 Chrome"的机器上也能被验证，
      否则它只会在 CI 上坏、而开发机永远绿。 */
   chromeCandidates,
+  sweepStaleTemplates,
 };

package/ai/shot.js

@@ -34,9 +34,9 @@
 var fs = require('fs');
 var os = require('os');
 var path = require('path');
-var { spawn } = require('child_process');
 var { pathToFileURL } = require('url');
 var pdf = require('./pdf.js');
+var connect = require('./cdp.js').connect;
 
 var DEFAULT_WIDTHS = [1440];
 var DEFAULT_HEIGHT = 900;
@@ -45,114 +45,6 @@ var DEFAULT_WAIT = 800;
    截断**不静默**：结果里带 truncatedAt，人/Agent 能看见。 */
 var MAX_FULL_HEIGHT = 10000;
 
-/** 极简 CDP 客户端：一个子进程、两个 fd、以 \0 分隔的 JSON。 */
-function connect(chromePath, profile) {
-  var child = spawn(chromePath, [
-    '--headless=new',
-    '--disable-gpu',
-    '--disable-extensions',
-    '--no-first-run',
-    '--no-default-browser-check',
-    /* 滚动条会占掉 15px 视口，且它本身不是页面内容 */
-    '--hide-scrollbars',
-    '--remote-debugging-pipe',
-    '--user-data-dir=' + profile,
-    'about:blank'
-  ], {
-    /* fd 0/1/2 给普通输出，3 = 命令（Chrome 读），4 = 事件（Chrome 写） */
-    stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe'],
-    windowsHide: true
-  });
-
-  var buf = Buffer.alloc(0);
-  var pending = Object.create(null);
-  var waiters = [];
-  var listeners = [];
-  var nextId = 0;
-  var dead = null;
-
-  function dispatch(msg) {
-    if (msg.id !== undefined && pending[msg.id]) {
-      var p = pending[msg.id];
-      delete pending[msg.id];
-      clearTimeout(p.timer);
-      if (msg.error) p.reject(new Error(p.method + '：' + (msg.error.message || JSON.stringify(msg.error))));
-      else p.resolve(msg.result);
-      return;
-    }
-    if (!msg.method) return;
-    for (var L = 0; L < listeners.length; L++) {
-      if (listeners[L].method === msg.method) listeners[L].fn(msg.params, msg.sessionId);
-    }
-    for (var i = waiters.length - 1; i >= 0; i--) {
-      var w = waiters[i];
-      if (w.method === msg.method && (!w.sessionId || w.sessionId === msg.sessionId)) {
-        waiters.splice(i, 1);
-        clearTimeout(w.timer);
-        w.resolve(msg.params);
-      }
-    }
-  }
-
-  child.stdio[4].on('data', function (chunk) {
-    buf = Buffer.concat([buf, chunk]);
-    var i;
-    while ((i = buf.indexOf(0)) >= 0) {
-      var raw = buf.subarray(0, i).toString('utf8');
-      buf = buf.subarray(i + 1);
-      var msg = null;
-      try { msg = JSON.parse(raw); } catch (e) { continue; }
-      dispatch(msg);
-    }
-  });
-  child.stdio[1].on('data', function () { /* 吞掉：Chrome 的正常输出没有信息量 */ });
-  child.stdio[2].on('data', function () { /* 同上；错误通过 CDP 的 error 字段回来 */ });
-  child.on('error', function (e) { dead = e; });
-  child.on('exit', function (code) {
-    dead = dead || new Error('Chrome 提前退出（退出码 ' + code + '）');
-    Object.keys(pending).forEach(function (k) {
-      clearTimeout(pending[k].timer);
-      pending[k].reject(dead);
-    });
-    pending = Object.create(null);
-    waiters.splice(0).forEach(function (w) { clearTimeout(w.timer); w.reject(dead); });
-  });
-
-  function send(method, params, sessionId, timeoutMs) {
-    return new Promise(function (resolve, reject) {
-      if (dead) return reject(dead);
-      var id = ++nextId;
-      var timer = setTimeout(function () {
-        delete pending[id];
-        reject(new Error(method + ' 超时（' + (timeoutMs || 15000) + 'ms 没有回应）'));
-      }, timeoutMs || 15000);
-      pending[id] = { resolve: resolve, reject: reject, timer: timer, method: method };
-      child.stdio[3].write(JSON.stringify({
-        id: id, method: method, params: params || {}, sessionId: sessionId
-      }) + '\0');
-    });
-  }
-
-  function waitEvent(method, sessionId, timeoutMs) {
-    return new Promise(function (resolve, reject) {
-      var timer = setTimeout(function () {
-        var at = waiters.findIndex(function (w) { return w.method === method && w.sessionId === sessionId; });
-        if (at >= 0) waiters.splice(at, 1);
-        reject(new Error('等 ' + method + ' 超时（' + (timeoutMs || 15000) + 'ms）'));
-      }, timeoutMs || 15000);
-      waiters.push({ method: method, sessionId: sessionId, resolve: resolve, reject: reject, timer: timer });
-    });
-  }
-
-  return {
-    send: send, waitEvent: waitEvent,
-    /* 常驻监听：异常/控制台消息可能在任意时刻到达，用一次性 waiter 会漏掉第二条起的所有 */
-    on: function (method, fn) { listeners.push({ method: method, fn: fn }); },
-    close: function () { try { child.kill(); } catch (e) { /* 已退出 */ } },
-    child: child
-  };
-}
-
 /** 页面在某个宽度下的量：溢出多少、谁溢出、有多高。 */
 var PROBE_JS = [
   '(function(){',

package/dist/01-tokens/page.css

@@ -1 +1 @@
-.page {margin:0;min-height:100vh;min-height:100dvh;background:var(--paper);color:var(--text-primary);font-family:var(--sans);font-size:var(--fs-base);line-height:var(--lh-base);-webkit-text-size-adjust:100%;padding-block:calc(env(safe-area-inset-top, 0px) + var(--sp-6)) calc(env(safe-area-inset-bottom, 0px) + var(--sp-6));padding-inline:max(env(safe-area-inset-right, 0px), var(--sp-4)) max(env(safe-area-inset-left, 0px), var(--sp-4));}.page *, .page *::before, .page *::after {box-sizing:border-box;}.page .wrap {margin-inline:auto;max-width:min(var(--measure-page), 100%);}.page .wrap--prose {max-width:min(var(--measure-prose), 100%);}.page h1 {font-family:var(--sans);font-size:var(--fs-2xl);font-weight:500;letter-spacing:var(--tracking-title);line-height:var(--lh-tight);margin:0 0 var(--sp-3);max-width:var(--measure-title);}.page h2 {font-size:var(--fs-lg);margin:var(--sp-7) 0 var(--sp-3);}.page .rule-top {border-top:1px solid var(--border-decor);padding-top:var(--sp-4);}.page .rule-bottom {border-bottom:1px solid var(--border-decor);padding-bottom:var(--sp-2);margin-bottom:var(--sp-4);}.page code {font-family:var(--mono);font-size:0.9em;background:var(--surface-sunken);padding:1px 4px;border-radius:var(--r-xs);}:where(.page) pre {overflow-x:auto;}.page .box {background:var(--surface);border:1px solid var(--border-decor);border-radius:var(--r-md);padding:var(--sp-5);}.page .box.bad {background:var(--surface-sunken);}.page .cmp {display:grid;grid-template-columns:minmax(0, 1fr) minmax(0, 1fr);gap:var(--sp-4);}.page .cmp--wide-first {grid-template-columns:minmax(0, 1.55fr) minmax(0, 1fr);}@media (max-width:640px) {.page .cmp, .page .cmp--wide-first, .page .cmp--clip {grid-template-columns:minmax(0, 1fr);}}.page .cmp__pane {padding:var(--sp-4);border:1px solid var(--border-decor);border-radius:var(--r-md);background:var(--surface-sunken);min-width:0;}.page .cmp--clip .cmp__pane {overflow:hidden;}.page .cmp__pane > h3 {margin:0 0 var(--sp-3);font-size:var(--fs-sm);font-weight:500;}.page .cmp__bad > h3 {color:var(--danger);}.page .cmp__good > h3 {color:var(--success);}.page .cmp__why {margin:var(--sp-3) 0 0;font-size:var(--fs-xs);line-height:1.6;color:var(--text-secondary);}
+.page {margin:0;min-height:100vh;min-height:100dvh;background:var(--paper);color:var(--text-primary);font-family:var(--sans);font-size:var(--fs-base);line-height:var(--lh-base);-webkit-text-size-adjust:100%;padding-block:calc(env(safe-area-inset-top, 0px) + var(--sp-6)) calc(env(safe-area-inset-bottom, 0px) + var(--sp-6));padding-inline:max(env(safe-area-inset-right, 0px), var(--sp-4)) max(env(safe-area-inset-left, 0px), var(--sp-4));}@media print {.page {min-height:0;padding-block-end:0;}}.page *, .page *::before, .page *::after {box-sizing:border-box;}.page .wrap {margin-inline:auto;max-width:min(var(--measure-page), 100%);}.page .wrap--prose {max-width:min(var(--measure-prose), 100%);}.page h1 {font-family:var(--sans);font-size:var(--fs-2xl);font-weight:500;letter-spacing:var(--tracking-title);line-height:var(--lh-tight);margin:0 0 var(--sp-3);max-width:var(--measure-title);}.page h2 {font-size:var(--fs-lg);margin:var(--sp-7) 0 var(--sp-3);}.page .rule-top {border-top:1px solid var(--border-decor);padding-top:var(--sp-4);}.page .rule-bottom {border-bottom:1px solid var(--border-decor);padding-bottom:var(--sp-2);margin-bottom:var(--sp-4);}.page code {font-family:var(--mono);font-size:0.9em;background:var(--surface-sunken);padding:1px 4px;border-radius:var(--r-xs);}:where(.page) pre {overflow-x:auto;}.page .box {background:var(--surface);border:1px solid var(--border-decor);border-radius:var(--r-md);padding:var(--sp-5);}.page .box.bad {background:var(--surface-sunken);}.page .cmp {display:grid;grid-template-columns:minmax(0, 1fr) minmax(0, 1fr);gap:var(--sp-4);}.page .cmp--wide-first {grid-template-columns:minmax(0, 1.55fr) minmax(0, 1fr);}@media (max-width:640px) {.page .cmp, .page .cmp--wide-first, .page .cmp--clip {grid-template-columns:minmax(0, 1fr);}}.page .cmp__pane {padding:var(--sp-4);border:1px solid var(--border-decor);border-radius:var(--r-md);background:var(--surface-sunken);min-width:0;}.page .cmp--clip .cmp__pane {overflow:hidden;}.page .cmp__pane > h3 {margin:0 0 var(--sp-3);font-size:var(--fs-sm);font-weight:500;}.page .cmp__bad > h3 {color:var(--danger);}.page .cmp__good > h3 {color:var(--success);}.page .cmp__why {margin:var(--sp-3) 0 0;font-size:var(--fs-xs);line-height:1.6;color:var(--text-secondary);}

package/dist/03-patterns/tabs/tabs.css

@@ -1 +1 @@
-.tabs {display:flex;flex-direction:column;gap:var(--sp-4);}.tabs--manual .tabs__tab[aria-selected="true"] {color:var(--text-secondary);font-weight:400;}@media (hover:hover) and (pointer:fine) {.tabs--manual .tabs__tab[aria-selected="true"]:hover {color:var(--text-primary);}}.tabs__list {display:flex;gap:var(--sp-1);border-bottom:1px solid var(--border-decor);position:relative;overflow-x:auto;overflow-y:hidden;scrollbar-width:none;}.tabs__list::-webkit-scrollbar {display:none;}.tabs--vertical {flex-direction:row;gap:var(--sp-4);}.tabs--vertical .tabs__list {flex-direction:column;border-bottom:0;border-inline-end:1px solid var(--border-decor);}.tabs__tab {appearance:none;background:none;border:0;margin-bottom:-1px;padding:var(--sp-3) var(--sp-4);font:inherit;font-size:var(--fs-base);color:var(--text-secondary);cursor:pointer;border-bottom:2px solid transparent;transition:color var(--dur-fast) var(--ease-out), border-color var(--dur-fast) var(--ease-out);white-space:nowrap;flex:0 0 auto;}.tabs--vertical .tabs__tab {margin-bottom:0;margin-inline-end:-1px;border-bottom:0;border-inline-end:2px solid transparent;text-align:start;}.tabs__tab[aria-selected="true"] {color:var(--text-primary);font-weight:600;border-bottom-color:var(--accent);}.tabs--vertical .tabs__tab[aria-selected="true"] {border-inline-end-color:var(--accent);}@media (hover:hover) and (pointer:fine) {.tabs__tab:not([aria-disabled="true"]):hover {color:var(--text-primary);background:var(--surface-sunken);}}.tabs__tab[aria-disabled="true"] {color:var(--text-tertiary);cursor:not-allowed;}.tabs__tab:focus-visible {outline:2px solid var(--accent);outline-offset:-2px;border-radius:var(--r-sm) var(--r-sm) 0 0;}.tabs__panel {padding:var(--sp-4) 0;}.tabs__panel[hidden] {display:none;}@media (prefers-reduced-motion:no-preference) {.tabs__panel--enter {animation:tabs-fade var(--dur-base) var(--ease-out);}}@keyframes tabs-fade {from {opacity:0;}to {opacity:1;}}
+.tabs {display:flex;flex-direction:column;gap:var(--sp-4);}.tabs--manual .tabs__tab[aria-selected="true"] {color:var(--text-secondary);font-weight:400;}@media (hover:hover) and (pointer:fine) {.tabs--manual .tabs__tab[aria-selected="true"]:hover {color:var(--text-primary);}}.tabs__list {display:flex;gap:var(--sp-1);border-bottom:1px solid var(--border-decor);position:relative;overflow-x:auto;overflow-y:hidden;scrollbar-width:none;}.tabs__list::-webkit-scrollbar {display:none;}.tabs--vertical {flex-direction:row;gap:var(--sp-4);}.tabs--vertical .tabs__list {flex-direction:column;border-bottom:0;border-inline-end:1px solid var(--border-decor);}.tabs__tab {appearance:none;background:none;border:0;margin-bottom:-1px;padding:var(--sp-3) var(--sp-4);font:inherit;font-size:var(--fs-base);color:var(--text-secondary);cursor:pointer;border-bottom:2px solid transparent;transition:color var(--dur-fast) var(--ease-out), border-color var(--dur-fast) var(--ease-out);white-space:nowrap;flex:0 0 auto;}.tabs--vertical .tabs__tab {margin-bottom:0;margin-inline-end:-1px;border-bottom:0;border-inline-end:2px solid transparent;text-align:start;}.tabs__tab[aria-selected="true"] {color:var(--text-primary);font-weight:600;border-bottom-color:var(--accent);}.tabs--vertical .tabs__tab[aria-selected="true"] {border-inline-end-color:var(--accent);}@media (hover:hover) and (pointer:fine) {.tabs__tab:not([aria-disabled="true"]):hover {color:var(--text-primary);background:var(--surface-sunken);}}.tabs__tab[aria-disabled="true"] {color:var(--text-tertiary);cursor:not-allowed;}.tabs__tab:focus-visible {outline:2px solid var(--accent);outline-offset:-2px;border-radius:var(--r-sm) var(--r-sm) 0 0;}.tabs__panel {padding:var(--sp-4) 0;}.tabs__panel[hidden] {display:none;}@media (prefers-reduced-motion:no-preference) {.tabs__panel--enter {animation:tabs-fade var(--dur-base) var(--ease-out);}}@keyframes tabs-fade {from {opacity:0;}to {opacity:1;}}@media print {.tabs__panel--enter {animation:none;transition:none;opacity:1;}}

package/dist/COSTS.md

@@ -46,14 +46,14 @@
 | 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 | `tabs` | 2.9 KB | 0.7 KB | 2.0 KB | **5.7 KB** | 29.2 KB | −23.5 KB |
 | pattern | `tooltip` | 2.9 KB | 0.5 KB | 2.0 KB | **5.4 KB** | 28.7 KB | −23.3 KB |
 | pattern | `tree` | 2.9 KB | 0.6 KB | 3.1 KB | **6.6 KB** | 30.3 KB | −23.7 KB |
 
 ## 三、全库
 
 - 全部组件都用上（min，含 tokens 一份）：**72.6 KB**
-- 源码版（带注释）全库 gzip：386.4 KB
+- 源码版（带注释）全库 gzip：386.7 KB
 
 > ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 69% 是注释，字节口径）。
 > 它的用途只有一个 —— 让人看清"dist 到底省了多少"。

package/docs/ACCESSIBILITY.md

@@ -5,7 +5,7 @@
 
 | 项目 | 值 |
 |---|---|
-| 声明适用版本 | agentcss `0.27.0` |
+| 声明适用版本 | agentcss `0.27.1` |
 | 声明日期 | 2026-11-06 |
 | 复核节奏 | 每次发版前重跑（`npm run gate` 内含全部证据） |
 | 范围 | 本库交付的 CSS / JS、全部 `demo.html`（组件页 + 图表页 + 组合页）、以及文档站生成的页面 |

package/docs/PRINT.md

@@ -258,9 +258,9 @@ node 05-audit/print-gate.js --pdf 某文件.pdf
 | `print-content-audit.js` | 该印的在不在？（屏幕可见 → 纸上消失？） | 它只在浏览器里量，不读 PDF |
 | `agentcss pdf` + `pdf-export-gate.js` | **导出成文件**这条路能用吗？（§八） | 它不做视觉比对 |
 
-前四个判的是"浏览器里按 Ctrl+P"，最后一个判的是"导出一份文件" ——
-**这是两条不同的渲染路径**（CDP `page.pdf()` vs Chrome 命令行 `--print-to-pdf`），
-`@page` 的来源与底色默认都不同。所以前者全绿推不出后者能用，两边各有各的判据。
+前四个判的是"浏览器里按 Ctrl+P"，最后一个判的是"导出一份文件"。两者都走 CDP，
+但 `@page` 来源、就绪条件、底色参数与输出保护不同；打印策略全绿推不出导出链没有
+旧文件假成功或异步漏内容，所以两边各有各的判据。
 
 `printPolicy` 是**有限枚举**，每个值对应一组能在浏览器里量的断言：
 
@@ -352,20 +352,36 @@ node 05-audit/print-policy-gate.js --selftest  # 反向控制
 npx agentcss pdf report.html --out report.pdf          # 默认 A4 / 18mm 15mm
 npx agentcss pdf report.html --out report.pdf --paper=letter --margin="20mm"
 npx agentcss pdf report.html --out report.pdf --max-pages=8
+npx agentcss pdf report.html --out report.pdf --ready-selector="#report-ready" --wait-ms=0
 ```
 
 `--paper` 支持 `a4` / `letter` / `a5` / `a3` / `legal`。边距是 CSS 简写
 （`18mm`、`"18mm 15mm"`、四段都认）。这两个参数靠**注入一条 `@page` 规则**实现，
 注入位置在使用者样式之后 —— 否则同特异性会被盖掉（同一个病）。
 
-零运行时依赖：用使用者机器上**已装好的** Chrome / Chromium / Edge。
-找不到就明确报错（退出码 3），不静默降级成空文件。指定位置：
+零运行时依赖：用使用者机器上**已装好的** Chrome / Chromium / Edge，经共享 CDP
+管道调用 `Page.printToPDF`，不打包 Puppeteer。找不到浏览器明确报错（退出码 3）：
 
 ```bash
 npx agentcss pdf report.html --out report.pdf --chrome="C:/Program Files/Google/Chrome/Application/chrome.exe"
 # 或环境变量 AGENTCSS_CHROME / CHROME_PATH
 ```
 
+#### 就绪、失败与旧文件保护
+
+导出顺序是：页面 `load` → `document.fonts.ready` → 可选可见元素 → 额外等待 →
+固定动画终态 → PDF。`--wait-ms` 默认 `800`，可设 `0`，上限 `60000`；它只是额外缓冲，
+**不是任意异步数据已经完成的证明**。动态报告应在数据与图表都渲染完后显示一个元素，
+再传 `--ready-selector="#report-ready"`；只存在但 `display:none`、不可见或没有尺寸不算就绪。
+
+整个导出默认有 60 秒总预算，超时退出码为 `4`。非法 CSS 选择器、空值与非法等待
+都是用法错误（退出码 `2`）。未捕获的页面 JS 异常会放进 JSON 的 `jsErrors` 供复核，
+普通 `console.error` 不会擅自让导出失败。
+
+浏览器只写暂存 PDF；确认本次成功后才原子替换输出文件。浏览器崩溃、就绪超时、
+非法选择器或产物校验失败时，**已有 PDF 保持不变，结论明确为失败**。超页数预算不同：
+完整的新 PDF 会保留，退出码 `5`，由作者决定如何拆改，绝不静默截断。
+
 ### 8.2 页数预算：超了报错，不替你截断
 
 ```bash
@@ -422,8 +438,8 @@ npx agentcss ai check doc.json --medium=paper
 ### 8.5 这条路谁守着
 
 ```bash
-node 05-audit/pdf-export-gate.js            # E1–E12 + 三条反向，约 11s，不需要静态服务
-node 05-audit/pdf-export-gate.js --selftest # 只跑"必须红"的几条，约 0.3s
+node 05-audit/pdf-export-gate.js            # E1–E20，不需要静态服务，约 40s
+node 05-audit/pdf-export-gate.js --selftest # 旧文件保护 / 超时 / 崩溃结论 / 非法参数
 ```
 
 | 判据 | 它问什么 | 实测抓到过什么 |
@@ -436,15 +452,27 @@ node 05-audit/pdf-export-gate.js --selftest # 只跑"必须红"的几条，约 0
 | E7 | `--margin` 真的影响页数吗 | 不注入 `@page` 时 60mm 与 10mm 页数相同 |
 | E8/E9″ | 没有浏览器时说人话吗；报错回显原始输入吗 | 退出码不对 / `abc` 被报成 `null` |
 | E11 | 产物本身合格吗（字体链 / 每页有文本） | 交给 `print-gate --pdf` 的分析器判，不重复实现解析 |
+| E13 | 页树 `/Count` 与 `/Type /Page` 数一致吗 | 分段页树按"第一个"取 ⇒ 50 页读成 8 页 |
+| E14 | ready-selector 等到的是内容，不只是耗时吗 | 延迟新增行的文字 runs 必须增加（48 → 143） |
+| E15 | 真实金融长文每页都有内容吗 | 透明面板与全空白尾页；现为 7 页、每页有文字 |
+| E16 | 浏览器失败会冒用旧 PDF 吗 | 旧文件 SHA-256 必须不变，结论必须失败 |
+| E17 | 就绪条件永不出现会无限等吗 | 有界 timeout，且不碰旧文件 |
+| E18 | 新参数写错会静默按默认值导出吗 | 非法 wait / 空值 / 非法 CSS 都是退出码 2 |
+| E19 | 浏览器起不来时给的是结论还是堆栈 | 去掉管道 error 监听 ⇒ 进程以 EPIPE 崩溃 |
+| E20 | 强杀留下的临时 HTML 会一直堆着吗 | 下次导出清掉 6 小时前的残留，刚生成的不碰 |
 
 🔴 E3 与 E7 是同一件事的两面：`@page` 注入是这套东西唯一的技术前提。
 把它改坏，门禁必须红 —— 实测过：注释掉注入那行，E3 报
 `a4=612×792pt`（回落成 Letter），E7 报 `10mm=2 页 / 60mm=2 页`。
 
+E14–E20 则保证“导出链说成功”与“这份产物真是本次、完整、可用”不会脱节。
+
 ### 8.6 不覆盖什么
 
 - **远程 URL 不注入 `@page`**：拿不到远程页面的字节，硬注入等于假装改了它。
   这类导出会明确打印"（远程页面：未注入 @page）"，纸幅由页面自己的 CSS 决定。
-- **视觉正确**：底色位置、边框粗细、图片裁切 —— 要栅格化比对，没做。
-- **页眉页脚 / 页码**：`--no-pdf-header-footer` 已关掉 Chrome 的默认页眉页脚，
-  但本工具不生成自己的。需要页码请用 `@page` + `counter(page)` 自己写。
+- **跨机器像素基线**：库内不把字体光栅化差异当成回归；正式交付仍需对实际 PDF
+  逐页栅格化，检查空白、裁切、边框与图表，并做一次实体打印打样。
+- **页眉页脚 / 页码**：导出器显式 `displayHeaderFooter:false`，本工具不生成自己的。
+  需要页码时用浏览器打印对话框的页眉页脚选项，或在自有 CDP/Puppeteer 层提供
+  `headerTemplate` / `footerTemplate`；不要假设 `@page + counter(page)` 在 Chrome 可用。

package/index.html

@@ -97,7 +97,7 @@ li a:active { background: var(--surface-sunken); }
   </p>
 </main>
 <footer class="wrap">
-  <p class="note">0.27.0 · 零第三方运行时依赖</p>
+  <p class="note">0.27.1 · 零第三方运行时依赖</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.27.0**.
+> Generated from `ai/components.json` + `ai/pitfalls*.json` + `ai/behaviors.json` at version **0.27.1**.
 > Do not edit by hand: run `python 05-audit/gen-llms.py` (freshness is gated).
 > Short version: `llms.txt`. Machine contract: `ai/*.json`.
 
@@ -20,7 +20,8 @@ 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
+npx agentcss ai pdf <page.html> --out page.pdf --wait-ms=800   # zero deps: your Chrome
+                    [--ready-selector="#report-ready"]        # wait for async content
 ```
 
 Every subcommand accepts `--json`. On failure it prints *one* JSON document —
@@ -56,7 +57,7 @@ and it reports horizontal overflow plus JS errors.
 | `pagination` | `pagination` | pattern | stable | 7.7 KB | `pagination.js` | 分页控件 | — |
 | `reveal` | `reveal` | pattern | stable | 4.0 KB | `reveal.js` | 入场动效：一个 data-reveal 属性六个方向，无 JS 时内容全可见 | — |
 | `states` | `state` | pattern | stable | 10.9 KB | — | 空/加载/错误/成功四种整块状态 | `empty-state-no-decoration` `text-injection-xss` |
-| `tabs` | `tabs` | pattern | stable | 5.9 KB | `tabs.js` | 选项卡切换 | — |
+| `tabs` | `tabs` | pattern | stable | 6.1 KB | `tabs.js` | 选项卡切换 | — |
 | `tooltip` | `tooltip` | pattern | stable | 3.5 KB | `tooltip.js` | 悬停/聚焦提示 | `popover-measure-after-render` `fixed-element-inventory` |
 | `tree` | `tree` | pattern | stable | 4.0 KB | `tree.js` | 可展开树形结构 | — |
 | `badge` | `badge` | primitive | stable | 6.1 KB | — | 状态标签：计数、分类、结果标记 | — |

package/llms.txt

@@ -25,7 +25,9 @@ npx agentcss ai check page.html --json               # check the page you actual
 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)
+npx agentcss ai pdf page.html --out page.pdf --max-pages=8 --ready-selector="#report-ready"
+                                                    # waits for load + fonts + visible async content;
+                                                    # zero deps; failed renders preserve an old PDF
 ```
 
 `check <doc.json>` and `check <page.html>` answer **different** questions: the JSON one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcss",
-  "version": "0.27.0",
+  "version": "0.27.1",
   "description": "移动 Web 组件库：CSS + 可选行为脚本，零第三方运行时依赖。样式用 bundler 引入，交互行为用 script 标签引入。",
   "keywords": [
     "css",