agentcss 0.25.6 → 0.26.0

package/04-recipes/longform/longform.html

@@ -479,7 +479,7 @@ th {
         哪怕会覆盖掉别人写的东西。
       </p>
 
-      <div class="table-wrap">
+      <div class="table-wrap" tabindex="0" role="region" aria-label="对照表（可横向滚动）">
         <table>
           <colgroup>
             <col style="width: 34%">
@@ -520,7 +520,7 @@ th {
         这套机制加上"准入控制"，让关键任务（姿态、点火）不会被普通计算饿死。
       </p>
 
-        <pre><code><span class="c-cmt"># 不是原文，是按手册重述的伪代码</span>
+        <pre tabindex="0"><code><span class="c-cmt"># 不是原文，是按手册重述的伪代码</span>
 if computer_overload():
     issue(1202)                  <span class="c-cmt"># 告警编号写入 AGC 计数区</span>
     <span class="c-cmt"># 不停机：停机会丢掉姿态信息，地面将失去唯一的实时数据源</span>
@@ -540,7 +540,7 @@ if computer_overload():
         包括读取真实的操作数、写入真实的寄存器地址。
       </p>
 
-        <pre><code><span class="c-cmt"># 一段能真正跑起来的最小例子</span>
+        <pre tabindex="0"><code><span class="c-cmt"># 一段能真正跑起来的最小例子</span>
 <span class="c-out">$</span> python3 -m agc --help
 <span class="c-out">$</span> ./yaAGC -t demo.agc        <span class="c-cmt"># 载入磁带并执行</span>
 <span class="c-out">AGC 0000 GO</span></code></pre>

package/04-recipes/report/demo.html

@@ -32,7 +32,7 @@
 <!-- ======================================================================== -->
 <h2 class="rule-top">先看取舍：三套版式各自放弃了什么</h2>
 
-<div class="table"><table>
+<div class="table" tabindex="0" role="region" aria-label="三种 profile 的结构差异（可横向滚动）"><table>
   <caption class="table__cap">表 A · 三种 profile 的结构差异（判据可验证，不是文案差异）</caption>
   <thead><tr>
     <th scope="col">profile</th>

package/04-recipes/table/README.md

@@ -65,6 +65,28 @@ var COLS = [
 
 ## 无障碍
 
+- **滚动容器必须能用键盘进入。** `.table` 是 `overflow:auto` 的二维滚动区域，
+  窄屏下会横向滚动；**纯 CSS 无法让它被 Tab 到**，必须在标记上给入口：
+
+  ```html
+  <div class="table table--financial" tabindex="0" role="region"
+       aria-label="A 股样例数据（可横向滚动）">
+    <table>…</table>
+  </div>
+  ```
+
+  三个属性缺一不可：`tabindex="0"`（进 Tab 序列）、`role="region"`（成为可命名地标）、
+  `aria-label`（读屏要念出"这是什么表"）。少了它们的后果是：只用键盘的用户
+  和部分读屏用户**看不到超出可视区的列**（WCAG 2.1.1）。
+  名字里带上 **「（可横向滚动）」**：只说"什么表"不告诉用户这里能滚，
+  焦点停上来时读屏不会提示还有更多列 —— 那正是这条规则要解决的问题。
+  图/图表容器同理，但名字应来自图注（`aria-labelledby` 指向 `<figcaption>`），
+  不要再手写一份同名文案（同一事实不留第二出处）。
+  > 这条由两道门禁守着：`table-check.js` ⑮ 在 320px 下逐个量「会滚的容器有没有入口」，
+  > `a11y-scan.js` 在同一个页面上补跑 320px 的 `scrollable-region-focusable`。
+  > 桌面宽（1280）下表格不溢出，那条 axe 规则根本不会触发 —— 所以窄屏必须单独判。
+  > ⚠️ 只有**真的会滚**的容器需要 `tabindex`；不滚的容器加上去只是多一个空的 Tab 停靠点。
+
 - 数据表用 `<th scope="col">` / `<th scope="row">`；多级表头第一层用 `scope="colgroup"`。
   复杂表格可用 `id` + `headers` 建立显式关联（本示例未用到，但结构支持）。
 - 排序状态放在 `<th aria-sort="ascending|descending">`，**不是**放在按钮上。

package/04-recipes/table/demo.html

@@ -131,7 +131,7 @@
     <strong>空格子和 0 是两件事</strong>：空格子读者分不清"没有数据"还是"漏了"，
     0 会被当成真实数值参与心算。
   </p>
-  <div class="table table--compact">
+  <div class="table table--compact" tabindex="0" role="region" aria-label="银行对账明细（可横向滚动）">
     <table>
       <caption class="table__cap">表 G · 银行对账明细（示例，含缺失值）</caption>
       <thead>
@@ -353,7 +353,7 @@
       });
     }
 
-    var h = '<div class="table table--financial"><table>' +
+    var h = '<div class="table table--financial" tabindex="0" role="region" aria-label="A 股样例数据（可横向滚动）"><table>' +
       '<caption class="table__cap">A 股样例数据（非真实财报，量级参照公开年报）· ' +
         '金额单位：万元 · 比率为比例值</caption>' +
       '<thead><tr>';
@@ -425,7 +425,7 @@
     { label: '时效 (150 °C)',  key: 'h150' }
   ];
 
-  var a = '<div class="table table--academic"><table>' +
+  var a = '<div class="table table--academic" tabindex="0" role="region" aria-label="时效温度对铝合金拉伸性能的影响（可横向滚动）"><table>' +
     '<caption class="table__cap">表 1 · 不同时效温度下铝合金的拉伸性能（示例数据）</caption>' +
     '<thead><tr><th scope="col" rowspan="2">合金牌号</th>';
   GROUPS.forEach(function (g) {
@@ -472,7 +472,7 @@
     return fixed(p, 3).replace(/^0\./, '.');
   }
 
-  var s = '<div class="table table--stats"><table>' +
+  var s = '<div class="table table--stats" tabindex="0" role="region" aria-label="OLS 估计结果（可横向滚动）"><table>' +
     '<caption class="table__cap">表 2 · 处理效应的 OLS 估计（示例数据，n = 412）</caption>' +
     '<thead><tr>' +
     '<th scope="col">项</th>' +
@@ -512,7 +512,7 @@
       why: '缺失 ⇒ 显示 —，不是 0，也不带符号' }
   ];
 
-  var p = '<div class="table"><table>' +
+  var p = '<div class="table" tabindex="0" role="region" aria-label="同一个数在不同列定义下的显示（可横向滚动）"><table>' +
     '<caption class="table__cap">同一个数、不同的列定义 ⇒ 不同的显示</caption>' +
     '<thead><tr><th scope="col">列定义</th><th scope="col">输入</th>' +
     '<th scope="col">渲染结果</th><th scope="col">为什么</th></tr></thead><tbody>';
@@ -547,7 +547,7 @@
       expect: '显示为字面字符' }
   ];
 
-  var e2 = '<div class="table"><table>' +
+  var e2 = '<div class="table" tabindex="0" role="region" aria-label="转义演示：动态文本按文本渲染（可横向滚动）"><table>' +
     '<caption class="table__cap">动态文本按**文本**渲染，不当 HTML 解释</caption>' +
     '<thead><tr><th scope="col">列定义</th><th scope="col">原始数据</th>' +
     '<th scope="col">渲染结果</th><th scope="col">验收点</th></tr></thead><tbody>';

package/09-assets/bar/bar.js

@@ -95,9 +95,35 @@
    *        并且只画（画布内的那一部分），不能画到坐标系外面去
    *     ③ **标注跟着堆叠顶端走**：标签写的是**该列合计**，不是第一个系列的值
    */
+  /* 可见文案默认值（F2 / 0.26.0）。
+     ⚠️ 这里用 `opt.text` 而不是 `labels` —— `bar.draw` 的 `labels`
+        早就是「X 轴标签」这个**数据**参数，改名是破坏性变更。
+        同类情况全库只此一处，已在 docs/L10N.md 写明。 */
+  var DEFAULT_TEXT = {
+    series: function (i) { return '系列 ' + i; },
+    clipped: function (n, isStack, max) {
+      return '有 ' + n + ' 个' + (isStack ? '类目的合计' : '数据')
+        + '超出量程（上限 ' + max + '），已按上限截断显示。';
+    }
+  };
+
+  /* ==== BEHAVIOR INJECT BEGIN: labels ==== */
+  var flLabels = function (defaults, src) {
+    src = src || {};
+    var out = {};
+    var k;
+    for (k in defaults) {
+      if (Object.prototype.hasOwnProperty.call(defaults, k)) {
+        out[k] = (src[k] === undefined || src[k] === null) ? defaults[k] : src[k];
+      }
+    }
+    return out;
+  };
+  /* ==== BEHAVIOR INJECT END: labels ==== */
   function draw(opt) {
     opt = opt || {};
     var host = opt.host;
+    var T = flLabels(DEFAULT_TEXT, opt && opt.text);
     if (!host) throw new Error('bar.draw: 缺少 host');
     if (opt.max === undefined || opt.max === null) {
       /* 🔴 铁律三：不替调用方决定量程。
@@ -286,7 +312,7 @@
         /* 🔴 用 textContent，不用 innerHTML —— 系列名来自调用方的数据 */
         li.appendChild(sw);
         var tx = document.createElement('span');
-        tx.textContent = se.name || ('系列 ' + (si + 1));
+        tx.textContent = se.name || T.series(si + 1);
         li.appendChild(tx);
         legendEl.appendChild(li);
       });
@@ -302,9 +328,7 @@
     } else if (clipped.length) {
       var p2 = document.createElement('p');
       p2.className = 'bar__note';
-      p2.textContent = '有 ' + clipped.length + ' 个' +
-                       (mode === 'stack' ? '类目的合计' : '数据') +
-                       '超出量程（上限 ' + max + '），已按上限截断显示。';
+      p2.textContent = T.clipped(clipped.length, mode === 'stack', max);
       host.appendChild(p2);
     }
 

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

@@ -110,7 +110,7 @@
     n.appendChild(this.ui);
 
     // 加载按钮
-    this.btn = el('button', 'mv__btn', '加载 3D 模型');
+    this.btn = el('button', 'mv__btn', LABELS.load);
     this.btn.type = 'button';
     this.btn.addEventListener('click', function () { self.load(); });
     this.ui.appendChild(this.btn);
@@ -120,23 +120,23 @@
        原来用 innerHTML 直接拼 ⇒ `<img onerror>` 这类值会被解析成节点。
        改成 textContent 组装：`<code>` 与 `<b>` 仍然存在，但文本永远只是文本。 */
     var fname = el('code', null, this.src.split('/').pop() || '—');
-    var strong = el('b', null, '点击后才下载');
-    this.hint.appendChild(document.createTextNode('模型 '));
+    var strong = el('b', null, LABELS.hintStrong);
+    this.hint.appendChild(document.createTextNode(LABELS.hintBefore));
     this.hint.appendChild(fname);
-    this.hint.appendChild(document.createTextNode(' 会'));
+    this.hint.appendChild(document.createTextNode(LABELS.hintBetween));
     this.hint.appendChild(strong);
-    this.hint.appendChild(document.createTextNode('，首屏不占流量。'));
+    this.hint.appendChild(document.createTextNode(LABELS.hintTail));
     this.ui.appendChild(this.hint);
 
     if (!hasWebGL()) {
-      this.fail('这台设备的浏览器不支持 WebGL，无法显示 3D 模型。');
+      this.fail(LABELS.noWebGL);
       this.btn.disabled = true;
     }
   };
 
   Viewer.prototype.makeIdle = function () {
     var box = el('div', 'mv__stage');
-    box.appendChild(el('div', 'mv__ph', '3D 模型'));
+    box.appendChild(el('div', 'mv__ph', LABELS.placeholder));
     return box;
   };
 
@@ -146,14 +146,14 @@
     this.state = 'error';
     this.ui.innerHTML = '';
     var s = el('div', 'mv__stage mv__stage--err');
-    s.appendChild(el('div', 'mv__ph', '3D 模型'));
+    s.appendChild(el('div', 'mv__ph', LABELS.placeholder));
     var p = el('p', 'mv__err', msg);
     s.appendChild(p);
     this.ui.appendChild(s);
     if (this.btn) this.ui.appendChild(this.btn);
     if (this.btn) {
       this.btn.disabled = false;
-      this.btn.textContent = '重试';
+      this.btn.textContent = LABELS.retry;
     }
   };
 
@@ -169,12 +169,12 @@
 
     this.ui.innerHTML = '';
     var stage = el('div', 'mv__stage');
-    this.statusNode = el('p', 'mv__status', '正在准备…');
+    this.statusNode = el('p', 'mv__status', LABELS.preparing);
     stage.appendChild(this.statusNode);
     this.ui.appendChild(stage);
 
     var t0 = (window.performance && performance.now) ? performance.now() : Date.now();
-    this.status('正在准备 3D 引擎…');
+    this.status(LABELS.preparingEngine);
     this.boot(null, t0, 0);
 
     /* 🔴🔴 **超时兜底**（实测：服务器上会卡死在 loading）
@@ -296,7 +296,7 @@
     xhr.onprogress = function (e) {
       if (e.lengthComputable && e.total) {
         self1.lastBytes = e.total;
-        self1.status('正在下载模型 ' + Math.round(e.loaded / e.total * 100) + '%');
+        self1.status(LABELS.downloading(Math.round(e.loaded / e.total * 100)));
       }
     };
     xhr.onload = function () {
@@ -396,6 +396,36 @@
 
   /* ---------- 对外 API ---------- */
 
+  /* 可见 / 读屏文案（F2 / 0.26.0）。
+     本组件由 `[data-mv]` 自动初始化、没有逐实例 opts ⇒ 用**模块级**设置：
+       `ModelViewer.setLabels({ load: 'Load 3D model', ... })`
+     ⚠️ 已知仍未覆盖的（列在 docs/L10N.md，不假装已做完）：
+        `mv__cap` 的说明句、`fail()` 的几条错误句 ——
+        它们含 `<b>` 结构与多个动态量，要改成节点拼装才能安全本地化。 */
+  var LABELS = {
+    load: '加载 3D 模型',
+    placeholder: '3D 模型',
+    retry: '重试',
+    preparing: '正在准备…',
+    preparingEngine: '正在准备 3D 引擎…',
+    hintBefore: '模型 ',
+    hintBetween: ' 会',
+    hintStrong: '点击后才下载',
+    hintTail: '，首屏不占流量。',
+    downloading: function (pct) { return '正在下载模型 ' + pct + '%'; },
+    noWebGL: '这台设备的浏览器不支持 WebGL，无法显示 3D 模型。'
+  };
+
+  function setLabels(patch) {
+    if (!patch) return;
+    for (var k in LABELS) {
+      if (Object.prototype.hasOwnProperty.call(LABELS, k)
+        && patch[k] !== undefined && patch[k] !== null) {
+        LABELS[k] = patch[k];
+      }
+    }
+  }
+
   var ModelViewer = {
     /** 扫描并初始化页面里的所有查看器 */
     update: function (root) {
@@ -421,6 +451,8 @@
     },
   };
 
+  ModelViewer.setLabels = setLabels;
+
   if (typeof window !== 'undefined') window.ModelViewer = ModelViewer;
 
   // @autoinit: [data-mv] —— 扫属性自动 update()（详见 API.md「自动初始化」）

package/09-assets/scientific-plot/demo.html

@@ -39,8 +39,8 @@
   本模块<strong>不做表达式求值</strong>。
 </p>
 <figure class="fig">
-  <div class="fig__box" id="fig1"></div>
-  <figcaption class="fig__cap">
+  <div class="fig__box" id="fig1" tabindex="0" role="region" aria-labelledby="fig1-cap"></div>
+  <figcaption class="fig__cap" id="fig1-cap">
     图 1 · 阻尼振荡位移随时间的变化。A = 1.00 m，λ = 0.35 s⁻¹，f = 1.20 Hz。
   </figcaption>
 </figure>
@@ -52,8 +52,8 @@
   也不据此推断显著性 —— 这两件事必须由测量者说清楚。
 </p>
 <figure class="fig">
-  <div class="fig__box" id="fig2"></div>
-  <figcaption class="fig__cap">
+  <div class="fig__box" id="fig2" tabindex="0" role="region" aria-labelledby="fig2-cap"></div>
+  <figcaption class="fig__cap" id="fig2-cap">
     图 2 · 五种催化剂在不同温度下的转化率（示例数据，误差棒为 ±1 个测量标准差）。
   </figcaption>
 </figure>
@@ -105,11 +105,11 @@
   后者画出的是一段<strong>不存在的趋势</strong>。
 </p>
 <figure class="fig">
-  <div class="fig__box" style="display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:var(--sp-3)">
+  <div class="fig__box" tabindex="0" role="region" aria-labelledby="figgap-cap" style="display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:var(--sp-3)">
     <div id="figGap"></div>
     <div id="figZero"></div>
   </div>
-  <figcaption class="fig__cap">
+  <figcaption class="fig__cap" id="figgap-cap">
     图 5 · 同一组数据，两种缺失处理。左：缺失断开（正确）。右：缺失当 0（错误，仅用于对照）。
   </figcaption>
 </figure>

package/API.md

@@ -376,6 +376,38 @@ python3 05-audit/prefix-build.py --prefix fl
 
 ---
 
+## 文案本地化（0.26.0 起）
+
+**库默认输出中文；`labels` 可覆盖用户可见 / 读屏会念到的文案。**
+
+```js
+Pagination.create(node, { labels: { prev: 'Previous', next: 'Next' } });
+Overlay.toast({ title: 'Saved', labels: { closeToast: 'Dismiss' } });
+Tooltip.setLabels({ region: 'Tooltip' });          // 模块级（属性初始化，无逐实例 opts）
+```
+
+- 值可以是字符串或函数（动态量用函数：`page(p, isCurrent)`、`uploading(pct)`）。
+- **不传时输出与 0.25.x 逐字相同** —— 升级补丁版本不会换掉界面语言。
+- `bar.draw` 是唯一例外：`labels` 已是「X 轴标签」这个**数据**参数，
+  它的文案覆盖叫 `text`。
+- 开发期错误信息（`throw new Error`）**不在覆盖范围**，它们不经过 UI。
+
+逐组件的键名、以及**已知仍未覆盖**的几处，见 `docs/L10N.md`。
+门禁：`05-audit/i18n-labels-gate.js`（静态禁硬编码 + 真浏览器验证覆盖生效、默认值不变）。
+
+### HTML 净化钩子
+
+`popover` / `drawer` 的字符串 HTML 入口可以接净化器：
+
+```js
+Popover.setSanitizer(function (html) { return DOMPurify.sanitize(html); });
+Drawer.setSanitizer(function (html) { return DOMPurify.sanitize(html); });
+```
+
+默认**不改变行为**（仍按"调用方已净化"处理），理由与责任边界见 `SECURITY.md`。
+
+---
+
 ## 破坏性变更怎么走
 
 公开**名字**（令牌名 / 类名 / 全局与类型成员 / 事件名）的移除走**登记制**：

package/CHANGELOG.md

@@ -16,6 +16,77 @@
 
 （无）
 
+## [0.26.0] - 2026-11-04
+
+这一版有两类改动：**修外部审计确认的缺陷**，以及**新增三个公开能力**
+（文案覆盖、HTML 净化钩子、toast 上限）。升级不需要改代码 ——
+新增能力都有默认值，且默认值与 0.25.6 行为一致。
+
+### Added
+
+- **文案本地化**：`labels` 可以覆盖用户可见 / 读屏会念到的文案。
+  逐实例入口 `Overlay.toast({ labels })`、`Drawer.open({ labels })`、
+  `Pagination.create(node, { labels })`、`new Upload(root, { labels })`、
+  `Select/Combobox/Dropdown/Tree/DateRange.create(root, { labels })`；
+  属性自动初始化的 `Tooltip` / `ModelViewer` 用模块级 `setLabels()`。
+  **不传时输出与 0.25.6 逐字相同**。`bar.draw` 的文案覆盖叫 `text`
+  （它的 `labels` 早就是 X 轴标签这个数据参数）。清单与已知剩余项见 `docs/L10N.md`。
+- **HTML 净化钩子**：`Popover.setSanitizer(fn)` / `Drawer.setSanitizer(fn)`，
+  也可逐次传 `sanitize`。默认**不改变行为**（仍按"调用方已净化"处理）——
+  静默自动净化会让既有页面里的 `<b>` / `<svg>` 突然消失。边界见 `SECURITY.md`。
+- **toast 同屏上限**：`Overlay.toast({ maxVisible })`，默认 4，`0` = 不限。
+  超出时摘掉**最旧的**一条（此前无上限，20 条并发提示会把屏幕铺满）。
+- `types/index.d.ts`：新增上列文案类型与 `ToastOptions` / `DialogOptions` /
+  `PopoverOptions` / `DrawerOpenOptions` / `UploadOptions` / `DropdownOptions` /
+  `NavOptions`；把 `ModelViewer` 从"构造函数"改正为 `{ update, refresh, setLabels }`
+  （按旧声明写 `new window.ModelViewer(el)` 会在运行时抛 TypeError）。
+
+### Fixed
+
+- `longform` 配方页：`.prose > img` 是**直接子代**选择器，而 Markdown 渲染出的图片
+  在 `<p>` 里 ⇒ `max-width:100%` 从未生效，600px 宽的图在 375px 视口横向溢出
+  246px、320px 溢出 301px。改为后代选择器（`> a` 在 0.9 踩过同一个坑，这次同一个坑换了标签）。
+- 可滚动的 `.table` / `.table-wrap` / `<pre>` / 图框在窄屏下**键盘进不去**
+  （WCAG 2.1.1）。补 `tabindex="0"` + `role="region"` + 「内容名（可横向滚动）」为名的
+  可访问名；图类用 `aria-labelledby` 指向 `<figcaption>`，不手写第二份文案。
+- 浏览器自动发现：Playwright 1.6x 的缓存目录名（`chrome-headless-shell-win64/` 等）
+  与代码里的候选**一个都不匹配**，此前靠系统 Chrome 兜底才跑得通。改为按可执行文件名
+  有界递归 + 读 `chromium.executablePath()`，并补 `%LOCALAPPDATA%` 路径。
+- 三处判据把"文本里出现过的字样"当成"当前生效的现状"：`contrast.py` 把注释里的旧色值
+  当真值、把 `@media dark` 块之后的浅色定义卷进暗色范围；`wiring-check.py` 把
+  `<style>` 里的 CSS 选择器当接线；`delta-check.js` 把 `<pre>` 里的用法示例当成
+  页面真的用了 `data-market`。三处都改成只看**会渲染 / 会执行**的结构。
+
+### Changed
+
+- 开发依赖 `puppeteer-core` 23 → 25（`npm audit` 从 9 high 到 0），CI 增加
+  `npm audit --omit=dev --audit-level=high`。
+- 根导出补显式 `import` 条件；README 讲清"运行时是 ESM、`engines>=18` 只代表语法可用，
+  `require()` 需要 Node ≥ 22.12"。
+
+### 新增 / 加强的门禁
+
+- `i18n-labels`：静态禁止「中文字面量直接进 `aria-label` / `textContent` / `el()` 文本位」，
+  并在真浏览器里传 `labels` 断言 DOM 真的变了、不传时仍是中文。
+- `md-inline-gate`：`md-render.py` 生成的单文件产物会把 `tokens.css` / `content.css`
+  整份内联成第二份副本，此前没有任何门禁守着它漂移（实测已落后 586 字符）。
+- `chrome-discovery-gate`：七种 Playwright 目录布局 × 两个入口 + 空目录不回落 + 旧写法元反向。
+- `a11y-scan` 增加 320px 的 `scrollable-region-focusable` 补扫 —— 一上线就抓出
+  `content` / `longform` / `analysis-report` / `scientific-plot` 四页真实违规。
+- `zoom-reflow` 的页面清单改为从文件系统枚举 `04-recipes/**/*.html`（43 → 49 页）——
+  上面那个 `.prose` 缺陷就活在不属于任何组件的配方页里。
+- `gen-behavior` 的扫描范围补上 `09-assets`：`bar` 的注入块否则是空的，
+  `flLabels is not defined` 只在浏览器门禁才炸。
+
+### 关于外部审计报告里的三条
+
+F8（demo 对比度）、F10（model-viewer 小溢出）、F12（缺 SemVer/废弃政策）经复核
+**不成立**：`.bad-err` / `.btn--naive` 都在 `.cmp__bad` 豁免容器内；本机 320px
+实测溢出 0；`STABILITY.md` / `DEPRECATIONS.md` / `deprecation-gate` 早已存在。
+没有为"关闭报告项"去改这三处。
+
+---
+
 ## [0.25.6] - 2026-11-04
 
 这一版**没有改组件、令牌、CSS 或运行时 JS**。改的是「装到手里的包可不可信」：

package/README.md

@@ -10,6 +10,23 @@ npm install agentcss
 
 The npm package is `agentcss`; the repository is `frontend-lib`. They are different things: the package name is what you install, the repository name is where the source lives.
 
+### Module format: ESM-only
+
+The JS entry points (`esm/*.mjs`) are **ESM only** — `exports` has no `require` condition.
+
+| You write | Node **≥ 20.19 / ≥ 22.12** | Node 18 – 20.18 |
+|---|---|---|
+| `import 'agentcss'` | ✅ | ✅ |
+| `require('agentcss')` | ✅ (Node's built-in require(ESM)) | ❌ `ERR_REQUIRE_ESM` |
+
+- On older runtimes use `await import('agentcss')`, or consume the CSS entry points only
+  (`agentcss/tokens.css` etc. are not JS and work on any Node version).
+- The shipped `*.js` files under `02-primitives/**` and `03-patterns/**` are **classic
+  scripts** for `<script>` tags, not CommonJS modules — they attach to `window.*`.
+- `"type": "commonjs"` is deliberate: it describes how those classic scripts are
+  *parsed*. Flipping it to `module` would make bundlers re-interpret them as ESM,
+  which is a breaking change.
+
 ## Docs and live demos
 
 - **Every demo page, one index** — https://owain323.github.io/frontend-lib/

package/README.zh-CN.md

@@ -60,6 +60,22 @@ npm install agentcss
 
 装出来的目录名就是 `agentcss`，`dist-tags.latest` 指向当前版本。
 
+### 模块格式：ESM-only（请先读这一条）
+
+`agentcss` 的 JS 入口（`esm/*.mjs`）**只有 ESM**，`exports` 里没有 `require` 条件。
+
+| 你的写法 | Node **≥ 20.19 / ≥ 22.12** | Node 18 ~ 20.18 |
+|---|---|---|
+| `import 'agentcss'` | ✅ | ✅ |
+| `require('agentcss')` | ✅（Node 自带的 require(ESM)） | ❌ `ERR_REQUIRE_ESM` |
+
+- 走 `require` 的旧环境请改用 `await import('agentcss')`，或只用 CSS 入口
+  （`agentcss/tokens.css` 这类**不是 JS**，任何 Node 版本都能直接引用）。
+- 包里的 `*.js`（`02-primitives/**`、`03-patterns/**`）是给 `<script>` 用的**经典脚本**，
+  不是 CommonJS 模块 —— 它们挂 `window.*`，不需要 bundler。
+- `type` 字段保持 `commonjs` 是**有意**的：它描述的是那批经典脚本的解析方式。
+  把它改成 `module` 会让 bundler 用 ESM 语义重新解析它们，属于破坏性变更。
+
 另外两条**同样真实可用**的路（内容与 registry 上那一份同源）：
 
 ```bash

package/SECURITY.md

@@ -44,10 +44,22 @@
 下面两处会把字符串**当 HTML 解析**。它们是**有意的 API**，不是疏漏 ——
 `popover` 要能放任意块级内容，`drawer` 要能放整页内容，只收文本就废了。
 
-| 文件 | 入口 | 谁负责净化 |
-|---|---|---|
-| `02-primitives/popover/popover.js` | `opts.html` | 调用方 |
-| `03-patterns/drawer/drawer.js` | `opt.content` | 调用方 |
+| 文件 | 入口 | 净化钩子 | 谁负责净化 |
+|---|---|---|---|
+| `02-primitives/popover/popover.js` | `opts.html` | `opts.sanitize` / `Popover.setSanitizer(fn)` | 调用方（或接钩子） |
+| `03-patterns/drawer/drawer.js` | `opt.content`（字符串） | `opt.sanitize` / `Drawer.setSanitizer(fn)` | 调用方（或接钩子） |
+
+**0.26.0 起有钩子，但默认不改变行为**：不传 `sanitize`、也不调 `setSanitizer()`
+时，两处仍然直接把字符串当 HTML 解析 —— 与 0.25.x 完全一致（静默"自动净化"
+会让既有页面里的 `<b>` / `<svg>` 突然消失，那也是一种破坏）。
+接 DOMPurify 只需一行：
+
+```js
+Popover.setSanitizer(function (html) { return DOMPurify.sanitize(html); });
+Drawer.setSanitizer(function (html) { return DOMPurify.sanitize(html); });
+```
+
+逐次覆盖优先于模块级：`Popover.attach(el, { html: s, sanitize: fn })`。
 
 **为什么本库不做净化**：净化需要一个 HTML 解析器或一份允许列表实现，而本库的目标是
 零运行时依赖 + Chromium 97 可用。给一个"看起来安全"的半吊子净化，比明确说

package/START-HERE.md

@@ -39,39 +39,39 @@
 | 标签 / 徽章 | `02-primitives/badge/badge.css` | 141 | — | 有状态标记就要（"已披露""停牌"） |
 | 卡片 | `02-primitives/card/card.css` | 283 | — | 有分组内容就要 |
 | 单选 / 多选 | `02-primitives/choice/choice.css` | 434 | — | 单选 / 多选就要 |
-| 下拉选择 | `02-primitives/select/select.css` | 151 | **必需 631** (`select.js`) | 原生 select 的外观或交互不够用就要 |
-| 可搜索选择 | `02-primitives/combobox/combobox.css` | 223 | **必需 480** (`combobox.js`) | 选项多到要搜索，或要选多个并留成标签就要 |
+| 下拉选择 | `02-primitives/select/select.css` | 151 | **必需 652** (`select.js`) | 原生 select 的外观或交互不够用就要 |
+| 可搜索选择 | `02-primitives/combobox/combobox.css` | 223 | **必需 503** (`combobox.js`) | 选项多到要搜索，或要选多个并留成标签就要 |
 | 开关 | `02-primitives/switch/switch.css` | 429 | — | 有"立即生效的设置"就要 |
 | 分隔线 | `02-primitives/separator/separator.css` | 73 | — | 要分开内容块就要 |
 | 加载骨架 | `02-primitives/skeleton/skeleton.css` | 114 | — | 数据还没到、先把版式占住就要 |
 | 进度条 / 环 | `02-primitives/progress/progress.css` | 228 | — | 有耗时过程要给进度就要 |
-| 浮层气泡 | `02-primitives/popover/popover.css` | 187 | **必需 325** (`popover.js`) | 要一段信息贴着触发元素浮出来就要 |
-| 日期区间 | `02-primitives/date-range/date-range.css` | 206 | **必需 310** (`date-range.js`) | 要选起止日期就要 |
+| 浮层气泡 | `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/accordion/accordion.css` | 453 | **必需 389** (`accordion.js`) | 长表单分段就要 |
-| 动作菜单 | `03-patterns/dropdown/dropdown.css` | 135 | **必需 555** (`dropdown.js`) | 要一组动作（新建 / 导出 / 删除）就要 |
-| 文字提示 | `03-patterns/tooltip/tooltip.css` | 89 | **必需 284** (`tooltip.js`) | 图标按钮或缩写需要一句话解释就要 |
-| 分页 | `03-patterns/pagination/pagination.css` | 195 | **必需 401** (`pagination.js`) | 数据多到要翻页就要 |
-| 树形 | `03-patterns/tree/tree.css` | 122 | **必需 464** (`tree.js`) | 层级数据（文件 / 组织 / 分类）要展开就要 |
-| 侧边抽屉 | `03-patterns/drawer/drawer.css` | 145 | **必需 378** (`drawer.js`) | 要从侧边滑出面板就要 |
-| 弹窗 / 吐司 | `03-patterns/overlay/overlay.css` | 338 | **必需 697** (`overlay.js`) | 需要弹层（吐司 / 模态）就要 |
+| 动作菜单 | `03-patterns/dropdown/dropdown.css` | 135 | **必需 575** (`dropdown.js`) | 要一组动作（新建 / 导出 / 删除）就要 |
+| 文字提示 | `03-patterns/tooltip/tooltip.css` | 89 | **必需 299** (`tooltip.js`) | 图标按钮或缩写需要一句话解释就要 |
+| 分页 | `03-patterns/pagination/pagination.css` | 195 | **必需 428** (`pagination.js`) | 数据多到要翻页就要 |
+| 树形 | `03-patterns/tree/tree.css` | 122 | **必需 484** (`tree.js`) | 层级数据（文件 / 组织 / 分类）要展开就要 |
+| 侧边抽屉 | `03-patterns/drawer/drawer.css` | 145 | **必需 416** (`drawer.js`) | 要从侧边滑出面板就要 |
+| 弹窗 / 吐司 | `03-patterns/overlay/overlay.css` | 338 | **必需 734** (`overlay.js`) | 需要弹层（吐司 / 模态）就要 |
 | 状态（空 / 加载 / 错 / 成功） | `03-patterns/states/states.css` | 269 | — | **凡是会异步取数就要** |
 | 表单校验 | `03-patterns/form-validation/form-validation.css` | 274 | — | 提交前要校验就要 |
 | 列表增删 | `03-patterns/list/list.css` | 162 | 可选 201 (`flip.js`，FLIP 增删动画，纯增强) | 列表会动态增删就要 |
 | 导航 / 目录 | `03-patterns/nav/nav.css` | 314 | **必需 425** (`nav.js`) · 可选 111 (`toc.js`，自动生成目录，纯增强) | 顶部要导航，或长文要目录就要 |
-| 长文排版 | `03-patterns/content/content.css` | 286 | — | 写文档 / 长文就要 |
+| 长文排版 | `03-patterns/content/content.css` | 298 | — | 写文档 / 长文就要 |
 | delta | `02-primitives/delta/delta.css` | 113 | — |  |
 | metric | `02-primitives/metric/metric.css` | 157 | — |  |
 | timeline | `02-primitives/timeline/timeline.css` | 152 | — | 有一串按时间排的事件（公告 / 大事记 / 版本记录）就要 |
-| upload | `02-primitives/upload/upload.css` | 490 | 可选 676 (`upload.js`，拖放 / 文件列表 / 校验；没有它基础形态照常工作) |  |
+| upload | `02-primitives/upload/upload.css` | 490 | 可选 709 (`upload.js`，拖放 / 文件列表 / 校验；没有它基础形态照常工作) |  |
 | reveal | `03-patterns/reveal/reveal.css` | 93 | 可选 175 (`reveal.js`，入场动效，纯增强；没有它内容直接可见) |  |
 | analysis-report | `04-recipes/analysis-report/analysis-report.css` | 226 | — |  |
 | app-shell | `04-recipes/app-shell/app-shell.css` | 588 | **必需 289** (`shell-nav.js`) |  |
 | detail-page | `04-recipes/detail-page/detail-page.css` | 190 | — |  |
 | report | `04-recipes/report/report.css` | 369 | — |  |
 | table | `04-recipes/table/table.css` | 409 | — |  |
-| bar | `09-assets/bar/bar.css` | 181 | **必需 324** (`bar.js`) |  |
-| model-viewer | `09-assets/model-viewer/model-viewer.css` | 143 | **必需 432** (`model-viewer.js`) |  |
+| bar | `09-assets/bar/bar.css` | 181 | **必需 348** (`bar.js`) |  |
+| model-viewer | `09-assets/model-viewer/model-viewer.css` | 143 | **必需 464** (`model-viewer.js`) |  |
 | scientific-plot | `09-assets/scientific-plot/scientific-plot.css` | 141 | **必需 604** (`scientific-plot.js`) |  |
 | sparkline | `09-assets/sparkline/sparkline.css` | 158 | **必需 508** (`sparkline.js`) |  |
 

package/ai/components.json

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