agentcss 0.26.0 → 0.27.1

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.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,7 +202,27 @@ function paperSpec(name) {
   return PAPERS[k] ? { key: k, ...PAPERS[k] } : null;
 }
 
-/** 注入到 `<head>` 末尾（**必须在使用者样式之后**，否则同特异性被覆盖 —— E254）。 */
+/* 硬杀（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>';
   if (/<\/head\s*>/i.test(html)) return html.replace(/<\/head\s*>/i, style + '</head>');
@@ -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（实测踩过，见 E264）。 */
       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/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": "这一版**有意放弃**了图/表编号（没有编号就引用不了「第几图」）。它不是缺件，是取舍；不作判据。"
+        }
+      ]
+    }
+  }
+}