agentcss 0.26.0 → 0.27.0

package/ai/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "generatedBy": "05-audit/gen-ai-contract.py",
-  "libraryVersion": "0.26.0",
+  "libraryVersion": "0.27.0",
   "$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.js

@@ -202,7 +202,7 @@ function paperSpec(name) {
   return PAPERS[k] ? { key: k, ...PAPERS[k] } : null;
 }
 
-/** 注入到 `<head>` 末尾（**必须在使用者样式之后**，否则同特异性被覆盖 —— E254）。 */
+/** 注入到 `<head>` 末尾（**必须在使用者样式之后**，否则同特异性被覆盖）。 */
 function injectSheet(html, css) {
   const style = '<style id="agentcss-paper" data-agentcss="paper">' + css + '</style>';
   if (/<\/head\s*>/i.test(html)) return html.replace(/<\/head\s*>/i, style + '</head>');
@@ -256,7 +256,7 @@ function exportPdf(o) {
     if (!Number.isInteger(b) || b < 1) {
       /* ⚠️ 用 String() 而不是 JSON.stringify：`JSON.stringify(NaN)` 是 `"null"`，
          于是 `--max-pages=abc` 会报「收到 null」—— 使用者据这句话会去查一个
-         根本不存在的 null（实测踩过，见 E264）。 */
+         根本不存在的 null（实测踩过）。 */
       return { ok: false, code: 'usage',
         message: '--max-pages 必须是 ≥1 的整数，收到 ' + String(o.budget) };
     }

package/ai/recipes.json

@@ -0,0 +1,86 @@
+{
+  "schemaVersion": "1.0.0",
+  "$comment": [
+    "版式的「必有件」—— 只收**能从标记本身判定**的那几条。",
+    "每一条都对应 04-recipes/report/README.md 里「三种版式的取舍」表中的一格；",
+    "那张表是这套系统存在的理由：同一份内容换一个阅读目的，该留什么、该放弃什么。",
+    "",
+    "🔴 为什么有的写在 requires、有的写在 unchecked：",
+    "  requires  = 有标记可查（少一个类就是确定的缺件），因此可以直接判红；",
+    "  unchecked = 说得清但判不了（「方法要写明」是内容判断），因此**只打印、不判过**。",
+    "  把后者塞进 requires 只能靠关键词匹配，那会造出一种「看起来在检查」的假绿 ——",
+    "  这套库宁可写「这条没查」，也不写「查过了」。"
+  ],
+  "recipes": {
+    "report/finance": {
+      "label": "report · 金融研究版",
+      "root": ".rep.rep--finance",
+      "css": "04-recipes/report/report.css",
+      "doc": "04-recipes/report/README.md",
+      "why": "给要快速比数字的人看：行长最短、字号小一档，靠关键数字条先给结论。",
+      "requires": [
+        {
+          "selector": ".rep__keyline",
+          "label": "关键数字条",
+          "why": "这一版的读者先看数、后看论证；没有数字条，标题下面就是一大段文字，等于放弃了它唯一的长处。"
+        },
+        {
+          "selector": ".rep__risk",
+          "label": "风险披露",
+          "why": "金融口径的结论必须带约束条件。少了它，页面读起来像建议，而不是分析。"
+        }
+      ],
+      "unchecked": [
+        {
+          "label": "长论证不超过两屏",
+          "why": "篇幅是内容判断，没有可查的标记。超过两屏的推理在这一版里会被跳过 —— 那是作者该拆的，不是工具能判的。"
+        }
+      ]
+    },
+    "report/technical": {
+      "label": "report · 科研技术版",
+      "root": ".rep.rep--technical",
+      "css": "04-recipes/report/report.css",
+      "doc": "04-recipes/report/README.md",
+      "why": "给要逐条核对的人看：行长最窄、行距最松，图与表自动编号。",
+      "requires": [
+        {
+          "selector": ".rep__source",
+          "label": "来源脚注",
+          "why": "这一版的读者会顺着结论回查原始材料；没有来源，逐条核对就无从开始。"
+        }
+      ],
+      "unchecked": [
+        {
+          "label": "方法写明",
+          "why": "「写了方法」没有可查的标记：它可能是一节、也可能是一段。判它需要读懂内容，工具不假装能判。"
+        }
+      ]
+    },
+    "report/magazine": {
+      "label": "report · 杂志编辑版",
+      "root": ".rep.rep--magazine",
+      "css": "04-recipes/report/report.css",
+      "doc": "04-recipes/report/README.md",
+      "why": "给通读一遍的人看：行长最宽、不编号，靠版面节奏而不是编号导航。",
+      "requires": [
+        {
+          "selector": ".rep__pull",
+          "label": "引语块",
+          "why": "这一版靠「停顿」制造节奏；没有引语块，长文会变成一整片同样密度的灰。"
+        },
+        {
+          "selector": ".rep__fig--wide",
+          "label": "出血宽图",
+          "why": "宽图是这一版唯一的视觉重音。全篇只有正文列宽的图，读起来和别的版式没有区别。"
+        }
+      ],
+      "unchecked": [
+        {
+          "label": "审计级追溯",
+          "why": "这一版**有意放弃**了图/表编号（没有编号就引用不了「第几图」）。它不是缺件，是取舍；不作判据。"
+        }
+      ]
+    }
+  }
+}

package/ai/scaffold.js

@@ -0,0 +1,195 @@
+/*
+ * scaffold.js — 三个「最小壳」：正确的骨架，不含内容
+ *
+ * ============================================================================
+ * 🔴 为什么给壳，而不是给模板引擎
+ * ----------------------------------------------------------------------------
+ * 这一层最容易做歪的方向是"喂一段内容，吐一页报告" —— 那需要解析输入、
+ * 决定结构、再选版式，最后产出的东西**没法被断言**（对不对取决于读的人）。
+ *
+ * 这里只做一件事：把**前置条件**给对。漏一条 `<link>`、少一层 `.rep__grid`、
+ * 把文章标题写成 h3，页面不会报错，只会静默地长得不对 —— 而这些都是
+ * "知道就不会错、不知道就一定会错"的东西。
+ *
+ * ⇒ 壳只保证三件事：
+ *   ① 引对了样式表（少一个 = 那部分完全没样式）
+ *   ② 骨架层级对（.rep > header > .rep__grid > .rep__body/.rep__aside）
+ *   ③ 每一版**必有件**的位置留出来了（ai/recipes.json 里那几条）
+ *
+ * ⚠️ 三个壳都必须能通过 `ai check --html --recipe=<自己>`。
+ *    这不是口号：05-audit/html-check-gate.js 每次都会把三个壳跑一遍，
+ *    壳和判据一旦对不上就红。壳里少写一个必有件，门禁当场抓到。
+ */
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+var AI = __dirname;
+
+/** 壳里出现的 CSS 清单（相对库根）。只列真正用到的，不多引。 */
+var SHEETS = [
+  '01-tokens/tokens.css',
+  '01-tokens/typography.css',
+  '01-tokens/page.css',
+  '04-recipes/table/table.css',
+  '04-recipes/report/report.css'
+];
+
+function head(title, cssPrefix) {
+  var p = String(cssPrefix || 'node_modules/agentcss').replace(/\/+$/, '');
+  var links = SHEETS.map(function (s) {
+    return '<link rel="stylesheet" href="' + p + '/' + s + '">';
+  }).join('\n');
+  return '<!doctype html>\n'
+    + '<html lang="zh-CN">\n'
+    + '<head>\n'
+    + '<meta charset="utf-8">\n'
+    + '<meta name="viewport" content="width=device-width, initial-scale=1">\n'
+    + '<title>' + title + '</title>\n'
+    + links + '\n'
+    + '</head>\n';
+}
+
+/* 表格：三个壳共用。caption + th[scope] 是硬要求，壳里就写对，
+   免得使用者照着抄的时候把这两条一起漏掉。 */
+function table() {
+  return '          <div class="table">\n'
+    + '            <table>\n'
+    + '              <caption>表 1 · 三组对比（写"这张表比的是什么"，不是"这是数据"）</caption>\n'
+    + '              <thead>\n'
+    + '                <tr><th scope="col">项目</th><th scope="col">A 组</th>'
+    + '<th scope="col">B 组</th><th scope="col">C 组</th></tr>\n'
+    + '              </thead>\n'
+    + '              <tbody>\n'
+    + '                <tr><th scope="row">指标一</th><td>—</td><td>—</td><td>—</td></tr>\n'
+    + '                <tr><th scope="row">指标二</th><td>—</td><td>—</td><td>—</td></tr>\n'
+    + '              </tbody>\n'
+    + '            </table>\n'
+    + '          </div>\n';
+}
+
+function figure(wide) {
+  return '          <figure class="rep__fig' + (wide ? ' rep__fig--wide' : '') + '">\n'
+    + '            <!-- 放图：09-assets/scientific-plot 的容器 id，或直接 <img src alt> -->\n'
+    + '            <div id="chart"></div>\n'
+    + '            <figcaption class="rep__cap">图 1 · 图说（说清"看什么"，不是"这是什么"）</figcaption>\n'
+    + '          </figure>\n';
+}
+
+function section(title, body) {
+  return '        <section class="rep__sec">\n'
+    + '          <h3>' + title + '</h3>\n'
+    + body
+    + '        </section>\n';
+}
+
+/* 三种版式各自的那一段。顺序刻意与 README 的取舍表一致。 */
+var VARIANTS = {
+  'report/finance': {
+    label: 'report · 金融研究版',
+    rootClass: 'rep rep--finance',
+    title: '标题：把结论写在标题里',
+    kicker: '行业跟踪 · 金融研究版',
+    standfirst: '导语：先说结论与它成立的条件，再说依据。读者读完这一段就该知道要不要往下看。',
+    before: '    <!-- 关键数字条：这一版的读者先看数、后看论证（ai/recipes.json: rep__keyline） -->\n'
+      + '    <div class="rep__keyline">\n'
+      + '      <div><b>读数一</b><span>—</span></div>\n'
+      + '      <div><b>读数二</b><span>—</span></div>\n'
+      + '      <div><b>读数三</b><span>—</span></div>\n'
+      + '    </div>\n',
+    body: '',
+    after: '    <!-- 风险披露：这一版必须有（ai/recipes.json: rep__risk） -->\n'
+      + '    <p class="rep__risk">风险披露：把结论的适用条件、数据口径与不确定性写在这里。'
+      + '没有这一段的金融结论读起来像建议，而不是分析。</p>\n',
+    aside: '次要读数放这里。放不下的大图不要塞边注 —— 边注只有 14em。'
+  },
+  'report/technical': {
+    label: 'report · 科研技术版',
+    rootClass: 'rep rep--technical',
+    title: '标题：说清对象与方法',
+    kicker: '实验报告 · 科研技术版',
+    standfirst: '导语：一句话说清做了什么、得到什么、结论的置信边界在哪。',
+    before: '',
+    body: '',
+    after: '    <!-- 来源脚注：这一版必须有（ai/recipes.json: rep__source） -->\n'
+      + '    <p class="rep__source">来源：数据出处、采集时间与口径。逐条核对的人会顺着这里回查原始材料。</p>\n',
+    aside: '术语与口径写这里。这一版的读者会逐条核对，边注用来放"不影响主线但需要说明"的东西。'
+  },
+  'report/magazine': {
+    label: 'report · 杂志编辑版',
+    rootClass: 'rep rep--magazine',
+    title: '标题：用一个具体的画面开头',
+    kicker: '长报道 · 杂志编辑版',
+    standfirst: '导语：把读者带进场景，而不是先给结论。这一版是通读的，不是查数的。',
+    before: '    <!-- 引语块：这一版靠停顿制造节奏（ai/recipes.json: rep__pull） -->\n'
+      + '    <blockquote class="rep__pull">一句能被单独引用的话。它应该是全文的转折点，不是摘要。</blockquote>\n',
+    body: '',
+    after: '',
+    aside: '短提醒放这里。这一版没有编号，边注是唯一的"旁白"通道。'
+  }
+};
+
+/**
+ * @param {string} id      版式名（见 ai/recipes.json）
+ * @param {object} [opts]  `{cssPrefix}` —— 样式表前缀，默认 `node_modules/agentcss`
+ * @returns {{ok:true, html:string, id:string, requires:string[]}|{ok:false, message:string}}
+ */
+function render(id, opts) {
+  opts = opts || {};
+  var v = VARIANTS[id];
+  if (!v) {
+    return { ok: false, message: '未知版式：' + id + '（可用：' + Object.keys(VARIANTS).join(' / ') + '）' };
+  }
+  var wide = id === 'report/magazine';
+
+  var body = '        <section class="rep__sec">\n'
+    + '          <h3>第一节：先给判断，再给依据</h3>\n'
+    + '          <p>正文。这一段的每句话都应该能被上一段的数字或下一段的图支撑；'
+    + '撑不住的删掉。</p>\n'
+    + figure(wide)
+    + table()
+    + '        </section>\n'
+    + section('第二节：把限制写清楚', '          <p>适用的边界、数据口径、以及"这一版有意不做什么"。</p>\n');
+
+  var html = head(v.title, opts.cssPrefix)
+    + '<body class="page">\n'
+    + '<main class="wrap">\n'
+    + '  <!-- 由 `agentcss ai scaffold` 生成：只给壳，不给内容。\n'
+    + '       写完跑：agentcss ai check 本文件 --recipe=' + id + ' -->\n'
+    + '  <article class="' + v.rootClass + '">\n'
+    + '    <header>\n'
+    + '      <p class="rep__kicker">' + v.kicker + '</p>\n'
+    + '      <h2 class="rep__title">' + v.title + '</h2>\n'
+    + '      <p class="rep__standfirst">' + v.standfirst + '</p>\n'
+    + '      <ul class="rep__meta"><li>作者</li><li>日期</li><li>版本 v1</li></ul>\n'
+    + '    </header>\n'
+    + v.before
+    + '    <div class="rep__grid">\n'
+    + '      <div class="rep__body">\n'
+    + body
+    + '      </div>\n'
+    + '      <aside class="rep__aside">' + v.aside + '</aside>\n'
+    + '    </div>\n'
+    + v.after
+    + '  </article>\n'
+    + '</main>\n'
+    + '</body>\n'
+    + '</html>\n';
+
+  var requires = [];
+  try {
+    var all = JSON.parse(fs.readFileSync(path.join(AI, 'recipes.json'), 'utf8'));
+    requires = ((all.recipes[id] || {}).requires || []).map(function (r) { return r.selector; });
+  } catch (e) { /* 读不到就不报；门禁会盯 recipes.json */ }
+
+  return { ok: true, html: html, id: id, requires: requires };
+}
+
+function list() {
+  return Object.keys(VARIANTS).map(function (k) {
+    return { id: k, label: VARIANTS[k].label };
+  });
+}
+
+module.exports = { render: render, list: list, VARIANTS: VARIANTS, SHEETS: SHEETS };

package/ai/shot.js

@@ -0,0 +1,345 @@
+/*
+ * shot.js — 把页面截成 PNG（给定宽度、可选整页）
+ *
+ * ============================================================================
+ * 🔴 为什么不用 `chrome --screenshot --window-size=390,844`
+ * ----------------------------------------------------------------------------
+ * 因为它**会撒谎**。Windows 上窗口有最小宽度，`--window-size=390` 拿到的
+ * 实际视口是 **500px**（实测 innerWidth=500），而 `--screenshot` 只按 390 裁一刀。
+ * 结果是一张"看起来是 390 宽"的图：文字在右边缘被切掉、媒体查询按 500 生效 ——
+ * 你据此判断"窄屏没问题"，其实从没看过 390。
+ *
+ * 这类失败最贵的地方在于**它不报错**：图是好的、能打开、只是内容不对。
+ * 所以这里走 Chrome 的调试管道（`--remote-debugging-pipe`，零依赖、不开端口），
+ * 用 `Emulation.setDeviceMetricsOverride` 把视口**设成**要的那个数，再截。
+ *
+ * ============================================================================
+ * 为什么是管道而不是 `--remote-debugging-port`
+ * ----------------------------------------------------------------------------
+ * 端口版要处理：端口占用、防火墙弹窗（Windows 首次监听会弹）、启动竞态
+ * （等调试端口文件出现的时机）、以及同一个 profile 被复用时的锁。
+ * 管道版把这些全绕开：读写走子进程的 fd 3/4，消息以 `\0` 分隔的 JSON。
+ * 代价是自己拼十几行帧处理 —— 比处理上面四件事便宜得多。
+ *
+ * ============================================================================
+ * 它**不是**视觉基线
+ * ----------------------------------------------------------------------------
+ * 基线（逐字节比对）由 `05-audit/shot-baseline.py` 管，那套要考虑字体、
+ * 双平台产物与指纹。这里的产物是给人/给 Agent **看一眼**的：
+ * 同一台机器、同样参数，两次逐字节一致（门禁验的就是这条）；
+ * 换一台机器不保证 —— 字体光栅化不一样，别拿它当跨机器判据。
+ */
+'use strict';
+
+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 DEFAULT_WIDTHS = [1440];
+var DEFAULT_HEIGHT = 900;
+var DEFAULT_WAIT = 800;
+/* 整页截图的高度上限。PNG 面积是 W×H×scale²，超了内存与耗时都会失控；
+   截断**不静默**：结果里带 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(){',
+  '  var d = document.documentElement;',
+  '  var vw = d.clientWidth;',
+  '  var over = [];',
+  '  var all = document.querySelectorAll("body *");',
+  '  for (var i = 0; i < all.length && over.length < 40; i++) {',
+  '    var e = all[i], r = e.getBoundingClientRect();',
+  '    if (r.width === 0 && r.height === 0) continue;',
+  '    if (r.right > vw + 1 || r.left < -1) {',
+  '      var cls = typeof e.className === "string" ? e.className : "";',
+  '      over.push(e.tagName.toLowerCase() + (cls ? "." + cls.trim().split(/\\s+/).join(".") : "")',
+  '        + " @" + Math.round(r.right));',
+  '    }',
+  '  }',
+  '  return JSON.stringify({',
+  '    viewport: vw, scrollWidth: d.scrollWidth, scrollHeight: d.scrollHeight,',
+  '    overflow: over.slice(0, 6), overflowCount: over.length',
+  '  });',
+  '})()'
+].join('\n');
+
+function slugWidth(w) { return String(w); }
+
+/**
+ * @param {object} o
+ * @param {string} o.src             本地 HTML 路径或 http(s) URL
+ * @param {string} o.out             输出文件；多宽度时须含 `{width}`
+ * @param {number[]} [o.widths]      视口宽度，默认 [1440]
+ * @param {number} [o.height]        视口高度，默认 900
+ * @param {boolean} [o.full]         整页（否则只截首屏）
+ * @param {number} [o.scale]         设备像素比，默认 1
+ * @param {number} [o.wait]          加载后额外等待（毫秒），默认 800
+ * @param {string} [o.chrome]
+ * @param {number} [o.timeoutMs]
+ * @returns {Promise<object>}
+ */
+async function shoot(o) {
+  o = o || {};
+  var t0 = Date.now();
+  if (!o.src) return { ok: false, code: 'usage', message: '缺少 src' };
+  if (!o.out) return { ok: false, code: 'usage', message: '缺少 out' };
+
+  var widths = o.widths && o.widths.length ? o.widths : DEFAULT_WIDTHS;
+  for (var i = 0; i < widths.length; i++) {
+    if (!Number.isInteger(widths[i]) || widths[i] < 200 || widths[i] > 4000) {
+      return { ok: false, code: 'usage',
+        message: '宽度必须是 200–4000 的整数，收到 ' + JSON.stringify(widths[i]) };
+    }
+  }
+  var height = o.height || DEFAULT_HEIGHT;
+  if (!Number.isInteger(height) || height < 200 || height > 4000) {
+    return { ok: false, code: 'usage',
+      message: '高度必须是 200–4000 的整数，收到 ' + JSON.stringify(o.height) };
+  }
+  var scale = o.scale === undefined ? 1 : Number(o.scale);
+  if (!(scale > 0 && scale <= 3)) {
+    return { ok: false, code: 'usage', message: '--scale 必须在 (0, 3]，收到 ' + JSON.stringify(o.scale) };
+  }
+
+  var remote = /^https?:\/\//i.test(o.src);
+  if (!remote) {
+    var srcAbs = path.resolve(o.src);
+    if (!fs.existsSync(srcAbs)) return { ok: false, code: 'usage', message: '找不到输入文件：' + srcAbs };
+    o.src = srcAbs;
+  }
+
+  var outTpl = String(o.out);
+  if (widths.length > 1 && outTpl.indexOf('{width}') < 0) {
+    return { ok: false, code: 'usage',
+      message: '截多个宽度时 --out 必须含 {width}（例：shot-{width}.png），'
+        + '否则 ' + widths.length + ' 张图会写进同一个文件，最后只剩一张' };
+  }
+
+  var chrome = pdf.resolveChrome(o.chrome);
+  if (chrome.error) return { ok: false, code: 'no-chrome', message: chrome.error };
+
+  var profile = fs.mkdtempSync(path.join(os.tmpdir(), 'agentcss-shot-'));
+  var cdp = connect(chrome.path, profile);
+  var shots = [];
+  var consoleErrors = [];
+  var budget = o.timeoutMs || 90000;
+  var deadline = Date.now() + budget;
+
+  try {
+    var target = await cdp.send('Target.createTarget', { url: 'about:blank' });
+    var attached = await cdp.send('Target.attachToTarget', { targetId: target.targetId, flatten: true });
+    var sid = attached.sessionId;
+
+    await cdp.send('Page.enable', {}, sid);
+    await cdp.send('Runtime.enable', {}, sid);
+    /* JS 异常要收集：截出一张"布局正确但内容没渲染"的图是最坏的产物，
+       而它通常就是一行 TypeError 造成的。 */
+    cdp.on('Runtime.exceptionThrown', function (p) {
+      if (consoleErrors.length >= 20) return;
+      var d = (p && p.exceptionDetails) || {};
+      var txt = (d.exception && d.exception.description) || d.text || '未捕获异常';
+      consoleErrors.push(String(txt).split('\n')[0]);
+    });
+    cdp.on('Runtime.consoleAPICalled', function (p) {
+      if (consoleErrors.length >= 20) return;
+      if (!p || p.type !== 'error') return;
+      var parts = (p.args || []).map(function (a) {
+        return a.value === undefined ? (a.description || a.type) : String(a.value);
+      });
+      consoleErrors.push('console.error: ' + parts.join(' '));
+    });
+
+    for (var w = 0; w < widths.length; w++) {
+      if (Date.now() > deadline) {
+        return { ok: false, code: 'timeout', message: '超出时间预算 ' + budget + 'ms', chrome: chrome.path, shots: shots };
+      }
+      var width = widths[w];
+      var w0 = Date.now();
+
+      await cdp.send('Emulation.setDeviceMetricsOverride', {
+        width: width, height: height, deviceScaleFactor: scale, mobile: false
+      }, sid);
+
+      var loaded = cdp.waitEvent('Page.loadEventFired', sid, 30000);
+      var nav = await cdp.send('Page.navigate', { url: remote ? o.src : pathToFileURL(o.src).href }, sid);
+      if (nav && nav.errorText) {
+        return { ok: false, code: 'render',
+          message: '页面加载失败（' + nav.errorText + '）：' + o.src, chrome: chrome.path, shots: shots };
+      }
+      await loaded;
+      if (o.wait) await new Promise(function (r) { setTimeout(r, o.wait); });
+
+      var probe = await cdp.send('Runtime.evaluate', {
+        expression: PROBE_JS, returnByValue: true
+      }, sid);
+      var info = {};
+      try { info = JSON.parse(probe.result.value); } catch (e) { info = {}; }
+
+      var clipH = height;
+      var truncated = null;
+      if (o.full) {
+        var want = info.scrollHeight || height;
+        clipH = Math.min(want, MAX_FULL_HEIGHT);
+        if (want > MAX_FULL_HEIGHT) truncated = want;
+      }
+
+      var shot = await cdp.send('Page.captureScreenshot', {
+        format: 'png',
+        captureBeyondViewport: !!o.full,
+        clip: { x: 0, y: 0, width: width, height: clipH, scale: 1 }
+      }, sid);
+      var png = Buffer.from(shot.data, 'base64');
+      if (png.length < 8 || png.readUInt32BE(0) !== 0x89504e47) {
+        return { ok: false, code: 'render', message: '产出的不是 PNG（' + png.length + ' 字节）',
+          chrome: chrome.path, shots: shots };
+      }
+
+      var outFile = path.resolve(outTpl.replace(/\{width\}/g, slugWidth(width)));
+      fs.mkdirSync(path.dirname(outFile), { recursive: true });
+      fs.writeFileSync(outFile, png);
+
+      shots.push({
+        width: width, out: outFile, bytes: png.length, ms: Date.now() - w0,
+        png: { width: png.readUInt32BE(16), height: png.readUInt32BE(20) },
+        full: !!o.full,
+        truncatedAt: truncated,
+        viewport: info.viewport === undefined ? null : info.viewport,
+        scrollWidth: info.scrollWidth === undefined ? null : info.scrollWidth,
+        scrollHeight: info.scrollHeight === undefined ? null : info.scrollHeight,
+        overflow: info.overflow || [],
+        overflowCount: info.overflowCount || 0
+      });
+    }
+
+    return {
+      ok: true, code: null, message: null, chrome: chrome.path,
+      scale: scale, wait: o.wait === undefined ? DEFAULT_WAIT : o.wait,
+      shots: shots, consoleErrors: consoleErrors, ms: Date.now() - t0
+    };
+  } catch (e) {
+    return { ok: false, code: 'render', message: String(e && e.message || e), chrome: chrome.path, shots: shots };
+  } finally {
+    cdp.close();
+    /* 清理必须**在进程退出前**做完：CLI 随后就 exit，挂 setTimeout 等于每截一张图
+       就在系统临时目录里留一个 Chrome profile（pdf.js 那边实测漏过 6 个）。
+       先等一下再删：Windows 上子进程刚 kill 时还握着文件句柄。 */
+    await new Promise(function (r) { setTimeout(r, 120); });
+    try { fs.rmSync(profile, { recursive: true, force: true, maxRetries: 3 }); }
+    catch (e) { /* 偶发 EBUSY，交给系统清理 */ }
+  }
+}
+
+module.exports = { shoot: shoot, DEFAULT_WIDTHS: DEFAULT_WIDTHS, DEFAULT_HEIGHT: DEFAULT_HEIGHT, DEFAULT_WAIT: DEFAULT_WAIT };