agentcss 0.11.13 → 0.11.16

package/CHANGELOG.md

@@ -16,6 +16,315 @@
 
 （无）
 
+## [0.11.16] - 2026-10-29
+
+**这一版没有新组件，补的是两处「说了但没做到」。**
+
+上一轮自评扣分最重的两条是：**没有对外弃用政策**（版本稳定性）
+和**无障碍树只验了 11 页**。两条都属于"文档里写得像有，实际上没有"的类型 ——
+比明说没做更坏，因为读者会按"有"的前提做决策。
+
+### ① 弃用政策：从「一句话承诺」变成「四类名字、双向门禁」
+
+此前 `ai/deprecations.json` 已经存在，但只覆盖**令牌名和类名**。
+于是「删掉 `Select.open()`」「把 `fl-select` 改名」这两件事
+**不在任何门禁的视野里** —— 而它们比删类名更容易伤到下游：
+类名删了样式塌了，看得见；方法删了是运行时 `undefined is not a function`，
+往往在用户点击之后才炸；事件名改了则**完全静默**，订阅方只是再也不被调用。
+
+现在 `kind` 四类，各自的取法都是静态可复算的（本门禁跑在 `MODE=fast` 层，
+不能为了一份名单去起浏览器）：
+
+| 类型 | 从哪来 | 抓得到 |
+|---|---|---|
+| `token` | `ai/tokens.json` | 删令牌、改名 |
+| `class` | `ai/components.json` | 删根类 / 变体 / 槽位 |
+| `api` | 源码里的 `global.X =`（大写开头）+ `types/index.d.ts` 的成员 | 删全局、删成员、删参数对象字段 |
+| `event` | `flEmit(el, 'fl-…')` 的字面量 | 改事件名 |
+
+实测（先红后修，不是"看着应该能抓"）：
+
+| 破坏方式 | 结果 |
+|---|---|
+| 把 `fl-nav-open` 改成 `fl-nav-opened` | 🔴 `fl-nav-open：基线里有、现在没了` |
+| 把 `TocApi.init` 改名 | 🔴 `TocApi.init：基线里有、现在没了` |
+
+过程中自己踩了两个洞，都记进了 `internal/ERRORS.md`：
+
+- **E131**：扩了 `KINDS`，但汇总行还写死 `cur_by['token'] | cur_by['class']`
+  ⇒ ⑦（未登记的移除）只对前两类算差集，新加的两类删了也不报。
+  门禁跑得更多、看着更忙，覆盖面反而更窄。修法：汇总一律遍历 `KINDS`，
+  且**每一类都要有自己的突变样本**（只打第一类证明不了后面接上了）。
+- **E132**：成员解析正则少一个 `re.M` ⇒ `^` 只匹配 body 开头，
+  而 `^\s+` 会吃掉前导换行，正好命中第一个成员，`AccordionInstance` 只收到 `root`。
+
+对外文档新建 **`docs/DEPRECATIONS.md`**，并与登记册**双向**比对
+（新门禁 `deprecation-doc-gate`）：
+
+- 登记册有、文档没写 ⇒ **漏告知**（读者以为它不会消失）
+- 文档写了、登记册没有 ⇒ **假承诺**（承诺了一个我们不会兑现的日期）
+- 版本号写错、替代写错、把已移除的名字写进"迁窗中"表 ⇒ 各自有独立判据
+
+顺带纠正了 `API.md` 里两句**说错的话**：原文写「只在**大版本**移除」
+「弃用项先加警告并保留一个完整版本周期」—— 而本库在 `0.7.x → 0.8.0`
+就删过名字（`state--delayed`），且组件脚本从不打印运行时警告。
+把话说满比说清更伤人，已改成与登记册一致的四条。
+
+### ② 无障碍树：11 页 → 全部 38 页，跑出 12 张无名表格
+
+`a11y-ax.js` 之前只转录 11 个「交互语义各不相同」的代表页。
+这个理由经不起一句追问：**没被转录的 27 页，凭什么认为它们没问题？**
+答案是没有依据 —— 判据只对被转录的页面生效。
+
+扩到全量后，第一次跑就红了 **12 条 `AX-1`，全部是同一类**：
+
+```text
+🔴 pagination      AX-1 [table] 可交互角色没有 accessible name
+🔴 report          AX-1 [table] …（2 张）
+🔴 echarts-adapter AX-1 [table] …（5 张）
+🔴 model-viewer    AX-1 [table] …（2 张）
+🔴 composition     AX-1 [table] …
+🔴 popover         AX-1 [table] …
+```
+
+这些是 demo 页里的**数据表**，紧跟在一个可见标题后面 —— 视觉用户读得到上下文，
+读屏用户读到的是"表格，没有名字"。修法给每张表加 `aria-label`，
+文字取自它上方那个标题（**不用** `<caption>`：可见 caption 会改变像素，
+而三套视觉基线要重录，那属于另一件事，不该混在无障碍修复里）。
+
+同时补了一条**覆盖完整性判据**：手写的页面清单必须**等于**磁盘上的全部
+`demo.html`。漏页（新增了 demo 忘了加清单）与幽灵页（清单里的文件不存在）
+都会直接红 —— 手写清单是「哪些页面要查」的第二份表述，两份必然漂移，
+这正是 `a11y-scan.js` 在 0.8.9 栽过的同一个坑。判据自己也做了反向控制
+（删一页 / 加幽灵页 / 重复登记，三种都必须红）。
+
+### ③ 门禁 203 → 204
+
+新增 `deprec-doc`，排在 `deprecation` 之后，仍在静态层内（不需要浏览器）。
+静态层本机约 3 分钟。
+
+### 已知边界
+
+- `api` 这一类里，只有 `api-contract-gate` 覆盖的组件是**实测**过
+  d.ts ↔ 运行时一致的；其余组件的成员**仅有声明**。
+  ⇒ 本判据保证「删声明之前必须登记」，不保证「运行时一定还有它」。
+- `data-*` 属性名、`detail` 字段、令牌默认值、CSS 变量默认值
+  **不在**基线里。这是"没做"，不是"量不了"，已在 `docs/DEPRECATIONS.md`
+  第四节逐条列出。
+- a11y 的人工部分仍然为零：真机读屏（NVDA / VoiceOver）一条记录都没有。
+  协议在 `docs/A11Y-MANUAL-PROTOCOL.md`，表格还是空的。
+
+---
+
+## [0.11.15] - 2026-10-29
+
+**「在真实项目里能不能用」这件事，现在有证据了。**
+
+前几版把验证工程做到了很高的水准：174 道门禁、可证伪的反例断言、变异探针。
+但有一类问题它一直抓不到 —— **这些检查全是对自家 demo 页做的**。
+一个 React / Next.js 项目把库装进去会怎样，仓库里没有任何东西回答过。
+
+这一版补的是那一半。查的时候发现三个**不会报错**的坑，每个都足以让
+接入者在第一步就放弃。
+
+### ① SSR 里 `import` 就崩（16/16 全崩）
+
+16 个行为脚本的收尾都是 `(function (global) { … })(window)`。
+在浏览器里没问题，在 Node / Next.js / Nuxt / Astro 里：
+
+```text
+ReferenceError: window is not defined
+    at Object.<anonymous> (03-patterns/accordion/accordion.js:485:3)
+```
+
+实测记录（修之前，逐个 `require`）：
+
+| 脚本 | 崩在 |
+|---|---|
+| 11 个 `… })(window)` | IIFE 调用处 |
+| `accordion` | 顶层 `typeof window.requestAnimationFrame`（会**先解引用** window） |
+| `nav` / `tabs` / `pagination` / `reveal` | 顶层 `document.readyState` |
+
+修法：IIFE 收尾统一为
+`})(typeof window !== 'undefined' ? window : globalThis);`，
+顶层 `document` 访问前加 `if (typeof document === 'undefined') return;`。
+现在 16/16 在 Node 里 `require` 成功，且 `globalThis.X` 拿到真 API。
+
+### ② 重复初始化会「点了没反应」（静默双触发）
+
+`init()` 没有幂等守卫。被调用两次时（SPA 路由切换、HMR、重复引入脚本）：
+
+- 旧实例的 click 监听**还挂在 root 上**（它的闭包还活着）
+- 新实例又挂一份 ⇒ 一次点击 toggle **两次** ⇒ 展开又收起
+
+肉眼看到的是「按钮点了没反应」，控制台干干净净。
+
+修法两条：`init()` 跳过已初始化的节点；构造器 `if (root.accordionInstance) return root.accordionInstance;`
+（返回对象覆盖 `this` 是 JS 合法行为）。`tabs` 同样处理。
+
+### ③ 有 `.d.ts`，却没有模块入口
+
+`types/index.d.ts` 声明了 `export declare const Select …`，
+而 `package.json` 的 `exports` 里**没有任何路径指向 JS 模块** ——
+`.` 指向 `index.html`，组件只能靠 `<script src>` 挂全局。
+类型在说谎：`import { Select } from 'agentcss'` 编译通过、运行时 undefined。
+
+修法：
+
+- 新增 `esm/`（**生成物**，17 个 `.mjs`：16 个组件 + `index.mjs`），
+  由 `05-audit/gen-esm.py` 从源码的 `global.X = …` 机械生成。
+  内容是「导入副作用 + 把 global 上的对象 re-export」，
+  **不复制实现** —— 门禁会断言 `esm` 导出与 `window.X` 是同一个对象。
+- `package.json` 新增 `"./esm"` 与 `"./esm/*"`，`files` 加 `esm/`。
+- `types/index.d.ts` 从 5 个组件补到 **16 个**（新增 Accordion / Tabs / Nav /
+  Pagination / Drawer / Overlay / Tooltip / Popover / Toc / Reveal / FLIP），
+  每条都对照过源码的真实赋值与原型方法名；收不窄的参数写 `object` 并注明，
+  不给假签名。
+- `sideEffects` 从 `["*.css", "*.js"]` 改为 `["**/*.css", "**/*.js", "**/*.mjs"]`。
+  **这是个真实的打包坑**：只匹配根目录的 glob 会让 bundler 把
+  `02-primitives/**/*.js` 当作无副作用模块 tree-shake 掉 —— 行为静默消失。
+
+### ④ 接入样板真的能跑了
+
+`examples/react-vite/README.md` 曾写着「这是 T-01 的交付物：证明这个库能被
+真实项目用上」，但那个目录里只有 `index.html` + `README.md` ——
+没有 `package.json`、没有构建、从没被执行过。**声称的证明不是证明。**
+
+新增 `examples/esm-native/`：原生 `<script type="module">`，零依赖零构建，
+由 `05-audit/example-esm-gate.js` 真打开、真点击、真量 computed style。
+不用 Vite 是因为装依赖的样板在别人机器上会因网络/版本差异跑不起来，
+「证明」就退化成「我机器上曾经证明过」。
+
+### ⑤ 门禁从 20 分钟降到 5–7 分钟（同一套判据）
+
+`check-all.sh` 改为「先入队、后并发执行、按序打印」：
+
+- 默认 4 路并发（`--parallel=N` 可调，`--serial` 回到逐条）。
+- 输出**顺序不变**：每条门禁的输出落到临时文件，全部跑完按注册顺序打印。
+  并发最容易毁掉「日志还能不能读」，而失败诊断是门禁存在的一半理由。
+- 会临时改工作区文件的门禁标 `@serial` 独占跑（`selftest-all` / `mutation-leak` /
+  `beh-reverse` / `pack-smoke` 等 9 条）。不标就互相污染 —— 实测出现过
+  「6 个自检弄脏工作区」的假红。
+- 实测：4 道最重的（zoom-reflow / rtl-render / beh-reverse / demo-claim）
+  串行 354s → 并发 142s，全部返回 0。
+- 全量实测：**203 道串行等价 1422 秒（23.7 分钟）→ 实际 9 分钟**，202 PASS
+  （唯一红的是 `release`，它要求先有 tag）。最慢的五道：`dark-cont` 142s、
+  `responsive` 140s、`zoom-reflow` 122s、`rtl-render` 89s、`visual-dark` 83s。
+
+### 门禁 197 → 203
+
+| 新增 | 判据 |
+|---|---|
+| `esm-gen` / `esm-gen-rev` | `esm/` 与源码的 `global.X =` 一一对应（生成物不漂移） |
+| `behavior-api` / `-rev` | A 无 DOM 加载 · B 重复构造返回同一实例且单击只切换一次 · C ESM 覆盖 |
+| `example-esm` / `-rev` | 样板页真能被浏览器打开、import 成功、行为与样式都生效 |
+
+另外两处判据升级：
+
+- `wiring` 现在认识 ESM：`import … from '../../esm/x.mjs'` 算作「引用了行为脚本」。
+  之前它只会看 `<script src>`，一个正确使用 ESM 的页面会被判「用了标记但没引脚本」
+  （自检加了 ⑥/⑥b 两条反向控制）。
+- `tsc-gate` 反例新增 4 条（无参 toggle / 字符串喂 pagesOf / attach 返回值当句柄 /
+  Nav 的静态 open），断言从 8 条增至 12 条。
+
+### 已知边界（如实写下来）
+
+- `esm/` 只覆盖 `02-primitives` 与 `03-patterns` 的行为脚本。
+  `09-assets` 的绘图脚本（Chart / Bar / ScientificPlot）与
+  `01-tokens/theme-toggle.js` 仍是 script 形态 —— 它们一个文件挂多个全局，
+  与「一文件一 API」的生成规则不同，硬套会生成名字打架的入口。
+- `Pagination.create()` 的实例成员未在类型层收窄（源码只挂了内部状态），
+  需要时读 `03-patterns/pagination/README.md`。
+- 真机读屏（NVDA / VoiceOver）仍需人工执行，`docs/A11Y-MANUAL-PROTOCOL.md` 的表格仍是空的。
+
+## [0.11.14] - 2026-10-29
+
+**「键盘到不了」这句话，现在能量了。**
+
+0.11.13 结束时，10 个页面仍是单栏反例。其中 5 页的登记里写着一句诚实话：
+「两块都可量，但这一页仍是单栏结构，升级成 cmp 要重排整页 —— 本轮没做，
+已知欠账」。这一版把那 5 页还掉了，并且在做的时候发现：**那句话有一半不准**
+—— 那些"可量"的差别是「按 Tab 能不能停上去」，而当时的指标表里
+根本没有能量它的东西。剩下的只有高度、宽度、字号这些代理量，
+拿来判"键盘到不了"是**间接**的（高度 0 暗示焦点没了，但那只是暗示）。
+
+### 新指标 `focus`
+
+`data-bad="input|focus|=0"` —— 数的是**真的能 Tab 到**的元素个数。
+实现是「`focus()` 成功 **且** `tabIndex >= 0`」，两个信号缺一不可，
+两种错都实测到了：
+
+| 元素 | tabIndex | 聚焦得成 | Tab 到得了 |
+|---|---|---|---|
+| `a[href]` | 0 | ✅ | ✅ |
+| `a`（没有 href） | 0 | ❌ | ❌ ← tabIndex 会撒谎 |
+| `input[disabled]` | 0 | ❌ | ❌ ← tabIndex 会撒谎 |
+| `div[tabindex="-1"]` | -1 | ✅ | ❌ ← 能聚焦 ≠ 能 Tab 到 |
+
+第二条是这一版第一次跑就踩到的：只判 `tabIndex >= 0`，把没有 href 的 `<a>`
+算成可聚焦（自检当场红了）；只判 `focus()`，把 roving tabindex 里
+`-1` 的那几项算成能 Tab 到（tabs 的正例量出 3，应该是 1）。
+两条都留在自检里，各占一条用例。
+
+### 7 个块从单栏改成成对
+
+| 页面 | 反例栏 | 正例栏 | 量的 |
+|---|---|---|---|
+| `choice` | `display:none` 的 input | `opacity:0` + 绝对定位 | `focus` 0 vs 1 |
+| `separator` | `div` + border-top | `<hr>` | `hr` 个数 0 vs 1 |
+| `switch` | `div role="switch"` | 原生 checkbox | `input` 个数 0 vs 1 |
+| `accordion` | `div` 当 trigger | heading 包 button | `button` 个数 0 vs 1 |
+| `accordion` | `max-height:0` | `hidden` | 链接 `focus` 1 vs 0 |
+| `tabs` | `div role="tab"` | `button role="tab"` | `focus` 0 vs 2 |
+| `tabs` | 三个 `tabindex="0"` | roving（只有一个 0） | `focus` 3 vs 1 |
+
+### 已知冲突：可点的徽标过不了自己的命中区门禁
+
+`badge` 本来也要改成成对（`div` 装可点 vs `a` 装可点），做到一半被
+`badge` 组件门禁拦住了：
+
+```
+FAIL ③ 命中区全部 ≥44px：A.badge badge--inf 视觉 54×24 命中 54×24
+```
+
+这不是演示写错 —— **是组件自身的矛盾**：README 说「要能点就用 button/a，
+样式照抄 `.badge`」，而徽标本体只有 24px 高，换上正确元素之后
+命中区就不达标（WCAG 2.5.5 要 44px）。也就是说，
+**本库目前没有任何一种写法能同时满足「可点的徽标」和「44px 命中区」**。
+
+这一版**没有**用内联样式把演示撑到 44px 蒙过门禁 —— 那是拿样式骗判据。
+徽标照旧是单栏，块上写明"配不成对的原因不是量不了，是组件还没解决"。
+真要修得动 `.badge--clickable` 的垂直内边距（或干脆在文档里禁止可点徽标），
+那是破坏性视觉变更，单独一版做。
+
+### 判据改成**按块**登记（原来按页）
+
+单栏块的理由从页面注释 `<!-- demo-claim:skip -->` 搬到块上
+`data-claim-skip="理由"`。原因不是审美，是这一版恰好会造出"混合页"：
+
+```
+separator：一块改成了 cmp（hr vs div），另一块（对比度）改不了
+switch   ：一块改成了 cmp（div vs 原生），另一块（label）改不了
+```
+
+按页判的话，只要加**一个** `cmp` 块，同页剩下的单栏反例就全部"洗白"了 ——
+门禁不看了，也不需要理由。所以先把这个洞堵上再改内容，否则改完就是假绿。
+页面级注释现在会**报错**，不忽略：两套机制并存比没有机制更坏。
+
+顺带：写了 `data-prose`（连标本都摆不出来）的块，不再要求写
+`data-claim-skip` —— 一条声明只覆盖一个问题，别让人把同一句话说两遍。
+
+### 覆盖
+
+- 对照块 **24 → 31**（30 页），每块两栏互斥且各自成立
+- 单栏块登记 **9 个**（逐块，理由是"视觉上必然相同"或"差别是时序/措辞/对比度"）
+- `data-prose` 声明 3 个（不变）
+- `demo-claim` 自检 **32 → 48 条**（29 必须红 + 19 必须绿）
+
+判据**证不了**的那些也没藏着：`switch` 的「label 被藏掉」两栏视觉必然相同，
+差别只在无障碍树里 —— 那一块登记为"写不出互斥断言"，证据指向
+`10-review/a11y-tree/switch.txt`，不是"看着差不多就算了"。
+
 ## [0.11.13] - 2026-10-29
 
 **先得有东西可看，才谈得上「两栏不一样」。**

package/CONTRIBUTING.md

@@ -8,7 +8,8 @@ npm run gate           # 全量：含浏览器类
 npm run gate:fast      # 只跑静态层，不用装浏览器
 ```
 
-全量是 **197 道门禁**（本机约 15–20 分钟：组件层要起浏览器，还要逐张比 95 张视觉截图）。
+全量是 **204 道门禁**（本机约 5–7 分钟：组件层要起浏览器，还要逐张比 96 张视觉截图；
+0.11.15 起默认 4 路并发执行，之前串行要 15–20 分钟）。
 只想确认没改坏静态契约的话用 `gate:fast`，几秒到几分钟。
 
 环境依赖只有一套（Node + Chromium），缺了对应的门禁会**跳过**（跳过不算通过）：
@@ -129,10 +130,15 @@ fix: <一句话说清改了什么、为什么>
    摆不出可见标本的（运行时行为、读屏输出、读者要自己按 Tab 才能发现、
    页面上没有图表实例），写在块上：
    `data-prose="为什么摆不出来"`。理由至少 8 个字，会被逐条打印出来，可以被反驳。
-   只有 `box bad` 单栏、没有 `cmp` 结构的页，还要在页面里写
-   `<!-- demo-claim:skip 为什么没有成对断言 -->`。
+   只有 `box bad` 单栏、配不出 `cmp` 结构的块，要在**块上**写
+   `data-claim-skip="为什么写不出互斥断言"`。
    **理由要区分"量不了"和"可量但没做"**：后者是欠账，写明白，别混进前者
    —— 一句"量化不了"掩盖一处没做的活，比不写更糟。
+9. **能配成对的，必须配成对。** `demo-claim` 里有一个指标（`focus`：
+   "按 Tab 能不能停上去"）就是为"键盘到不了"这类反例加的 ——
+   `choice` / `switch` / `accordion` / `tabs` 四页的单栏反例，
+   0.11.14 全部改成了成对结构，因为它们**本来就可量**，差的只是有人去重排。
+   ⇒ 写"量不了"之前先问一句：**是新指标的事，还是我没做？**
 
 ## 提 PR 之前
 

package/README.zh-CN.md

@@ -343,7 +343,7 @@ import 'agentcss/dist/02-primitives/button/button.css';
 | `ai/` | **机器可读契约**：`components.json` / `tokens.json` / schema / 校验器 / 命令行 |
 | `adapters/` | 场景适配层（如演示文稿），**不进核心** |
 | `benchmark/` | 兼容性基准（10 类编辑意图，当前无模型实测记录） |
-| `docs/` | `INVARIANT.md`（不变式）· `CONVENTIONS.md`（全局约定）· `ACCESSIBILITY.md`（无障碍）· `AI-CONTRACT.md`（与 AI 协作的契约）· `LAYER-BASELINE.md`（引擎能力基线） |
+| `docs/` | `INVARIANT.md`（不变式）· `CONVENTIONS.md`（全局约定）· `ACCESSIBILITY.md`（无障碍）· `DEPRECATIONS.md`（弃用与移除）· `AI-CONTRACT.md`（与 AI 协作的契约）· `LAYER-BASELINE.md`（引擎能力基线） |
 | `types/` | TypeScript 类型定义（描述 `window` 上的全局对象） |
 
 ## 示例与验证状态

package/START-HERE.md

@@ -47,20 +47,20 @@
 | 进度条 / 环 | `02-primitives/progress/progress.css` | 172 | — | 有耗时过程要给进度就要 |
 | 浮层气泡 | `02-primitives/popover/popover.css` | 187 | **必需 331** (`popover.js`) | 要一段信息贴着触发元素浮出来就要 |
 | 日期区间 | `02-primitives/date-range/date-range.css` | 206 | **必需 301** (`date-range.js`) | 要选起止日期就要 |
-| 标签页 | `03-patterns/tabs/tabs.css` | 172 | **必需 307** (`tabs.js`) | 同层级内容切换就要 |
-| 折叠面板（beta） | `03-patterns/accordion/accordion.css` | 453 | **必需 369** (`accordion.js`) | 长表单分段就要 |
+| 标签页 | `03-patterns/tabs/tabs.css` | 172 | **必需 316** (`tabs.js`) | 同层级内容切换就要 |
+| 折叠面板（beta） | `03-patterns/accordion/accordion.css` | 453 | **必需 389** (`accordion.js`) | 长表单分段就要 |
 | 动作菜单（beta） | `03-patterns/dropdown/dropdown.css` | 135 | **必需 451** (`dropdown.js`) | 要一组动作（新建 / 导出 / 删除）就要 |
 | 文字提示 | `03-patterns/tooltip/tooltip.css` | 89 | **必需 288** (`tooltip.js`) | 图标按钮或缩写需要一句话解释就要 |
-| 分页 | `03-patterns/pagination/pagination.css` | 195 | **必需 395** (`pagination.js`) | 数据多到要翻页就要 |
+| 分页 | `03-patterns/pagination/pagination.css` | 195 | **必需 401** (`pagination.js`) | 数据多到要翻页就要 |
 | 树形 | `03-patterns/tree/tree.css` | 122 | **必需 464** (`tree.js`) | 层级数据（文件 / 组织 / 分类）要展开就要 |
 | 侧边抽屉（beta） | `03-patterns/drawer/drawer.css` | 129 | **必需 258** (`drawer.js`) | 要从侧边滑出面板就要 |
 | 弹窗 / 吐司（beta） | `03-patterns/overlay/overlay.css` | 319 | **必需 563** (`overlay.js`) | 需要弹层（吐司 / 模态）就要 |
 | 状态（空 / 加载 / 错 / 成功） | `03-patterns/states/states.css` | 252 | — | **凡是会异步取数就要** |
 | 表单校验 | `03-patterns/form-validation/form-validation.css` | 263 | — | 提交前要校验就要 |
 | 列表增删 | `03-patterns/list/list.css` | 162 | 可选 201 (`flip.js`，FLIP 增删动画，纯增强) | 列表会动态增删就要 |
-| 导航 / 目录 | `03-patterns/nav/nav.css` | 314 | **必需 430** (`nav.js`) · 可选 111 (`toc.js`，自动生成目录，纯增强) | 顶部要导航，或长文要目录就要 |
+| 导航 / 目录 | `03-patterns/nav/nav.css` | 314 | **必需 433** (`nav.js`) · 可选 111 (`toc.js`，自动生成目录，纯增强) | 顶部要导航，或长文要目录就要 |
 | 长文排版 | `03-patterns/content/content.css` | 286 | — | 写文档 / 长文就要 |
-| reveal | `03-patterns/reveal/reveal.css` | 93 | 可选 172 (`reveal.js`，入场动效，纯增强；没有它内容直接可见) |  |
+| reveal | `03-patterns/reveal/reveal.css` | 93 | 可选 175 (`reveal.js`，入场动效，纯增强；没有它内容直接可见) |  |
 | analysis-report | `04-recipes/analysis-report/analysis-report.css` | 187 | — |  |
 | detail-page | `04-recipes/detail-page/detail-page.css` | 190 | — |  |
 | report | `04-recipes/report/report.css` | 364 | — |  |

package/ai/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "generatedBy": "05-audit/gen-ai-contract.py",
-  "libraryVersion": "0.11.13",
+  "libraryVersion": "0.11.16",
   "$comment": "机器可读的组件契约。slots = BEM 元素名（在本库里元素名就是插槽名），states.enum = 组件会在 DOM 上写出的 data-* 取值，states.legacyClass = 仍未收敛到 data 属性的历史状态类（INVARIANT I-8 未达标）。",
   "maturityCriteria": {
     "alpha": "缺 demo.html 或缺 05-audit 下的专属门禁 ⇒ 还没被机器验证过，不要用",
@@ -125,7 +125,9 @@
       },
       "aria": {
         "roles": [],
-        "attrs": []
+        "attrs": [
+          "label"
+        ]
       },
       "usesOtherNamespaces": [],
       "global": "ModelViewer",
@@ -1455,7 +1457,8 @@
           "main"
         ],
         "attrs": [
-          "hidden"
+          "hidden",
+          "label"
         ]
       },
       "usesOtherNamespaces": [],
@@ -1899,7 +1902,8 @@
       "aria": {
         "roles": [],
         "attrs": [
-          "hidden"
+          "hidden",
+          "label"
         ]
       },
       "usesOtherNamespaces": [],

package/ai/deprecations.schema.json

@@ -39,7 +39,7 @@
         "required": ["id", "kind", "name", "deprecatedIn", "removeIn", "reason"],
         "properties": {
           "id": { "type": "string", "minLength": 1 },
-          "kind": { "enum": ["token", "class"] },
+          "kind": { "enum": ["token", "class", "api", "event"] },
           "name": { "type": "string", "minLength": 1 },
           "deprecatedIn": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
           "removeIn": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
@@ -61,7 +61,7 @@
         "type": "object",
         "required": ["kind", "name", "removedIn"],
         "properties": {
-          "kind": { "enum": ["token", "class"] },
+          "kind": { "enum": ["token", "class", "api", "event"] },
           "name": { "type": "string", "minLength": 1 },
           "removedIn": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" },
           "replacement": {

package/dist/02-primitives/combobox/combobox.js

@@ -436,4 +436,4 @@ return String(s).replace(/[&<>"]/g, function (c) {
   }
 
   global.Combobox = { create: create };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

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

@@ -264,4 +264,4 @@ create: create,
 iso: iso, addDays: addDays, addMonths: addMonths,
 quarterOf: quarterOf, quarterRange: quarterRange,
 };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/02-primitives/popover/popover.js

@@ -254,4 +254,4 @@ get current() { return current; },
 };
 
 global.Popover = Popover;
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/02-primitives/select/select.js

@@ -446,4 +446,4 @@ set value(v) { selected = v == null ? null : String(v); paint(); },
 }
 
 global.Select = { create: create };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/accordion/accordion.js

@@ -1,4 +1,4 @@
-(function () {
+(function (global) {
 'use strict';
 
 var uid = 0;
@@ -28,7 +28,8 @@ return ev;
 
 function toArray(x) { return Array.prototype.slice.call(x); }
 
-var raf = (typeof window.requestAnimationFrame === 'function')
+var raf = (typeof window !== 'undefined' &&
+typeof window.requestAnimationFrame === 'function')
 ? window.requestAnimationFrame.bind(window)
 : function (fn) { return setTimeout(fn, 16); };
 
@@ -51,6 +52,8 @@ return null;
 }
 
 function Accordion(root, opts) {
+
+if (root && root.accordionInstance) return root.accordionInstance;
 this.root = root;
 this.opts = opts || {};
 this.items = toArray(root.querySelectorAll('.accordion__item'));
@@ -202,18 +205,21 @@ if (item) self.toggle(item);
 
 };
 
-window.Accordion = Accordion;
+global.Accordion = Accordion;
 
 function init() {
 var nodes = document.querySelectorAll('[data-accordion]');
 for (var i = 0; i < nodes.length; i++) {
+
+if (nodes[i].accordionInstance) continue;
 nodes[i].accordionInstance = new Accordion(nodes[i]);
 }
 }
 
+if (typeof document === 'undefined') return;
 if (document.readyState === 'loading') {
 document.addEventListener('DOMContentLoaded', init);
 } else {
 init();
 }
-})();
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/drawer/drawer.js

@@ -226,4 +226,4 @@ return { el: d, close: close };
 }
 
 global.Drawer = { open: open };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/dropdown/dropdown.js

@@ -362,4 +362,4 @@ destroy: function () { roving.destroy(); dismiss.destroy(); menu.hidden = true;
 }
 
 global.Dropdown = { create: create };
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/list/flip.js

@@ -114,4 +114,4 @@ if (done) { done(); }
 
 global.FLIP = { flip: flip, remove: removeWithAnimation };
 
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/nav/nav.js

@@ -1,4 +1,4 @@
-(function () {
+(function (global) {
 'use strict';
 
 var flEmit = function (el, name, detail) {
@@ -306,7 +306,7 @@ root.navInstance = new Nav(root, opts);
 return root.navInstance;
 };
 
-window.Nav = Nav;
+global.Nav = Nav;
 
 function init() {
 each(document.querySelectorAll('[data-nav]'), function (el) {
@@ -314,9 +314,10 @@ if (!el.navInstance) Nav.attach(el, {});
 });
 }
 
+if (typeof document === 'undefined') return;
 if (document.readyState === 'loading') {
 document.addEventListener('DOMContentLoaded', init);
 } else {
 init();
 }
-})();
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/nav/toc.js

@@ -73,4 +73,4 @@ global.removeEventListener('hashchange', update);
 
 global.Toc = { init: init };
 
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/overlay/overlay.js

@@ -395,4 +395,4 @@ return { el: box, close: close };
 
 global.Overlay = { toast: toast, dialog: dialog };
 
-})(window);
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/pagination/pagination.js

@@ -1,4 +1,4 @@
-(function () {
+(function (global) {
 'use strict';
 
 var flEmit = function (el, name, detail) {
@@ -263,11 +263,12 @@ return Math.max(1, Math.ceil((total || 1) / (pageSize || 20)));
 },
 };
 
-if (typeof window !== 'undefined') window.Pagination = API;
+global.Pagination = API;
 
+if (typeof document === 'undefined') return;
 if (document.readyState === 'loading') {
 document.addEventListener('DOMContentLoaded', function () { API.update(); });
 } else {
 API.update();
 }
-})();
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/03-patterns/reveal/reveal.js

@@ -130,9 +130,10 @@ enable();
 }
 }
 
+if (typeof document === 'undefined') return;
 if (document.readyState === 'loading') {
 document.addEventListener('DOMContentLoaded', auto, false);
 } else {
 auto();
 }
-}(this));
+})(typeof window !== 'undefined' ? window : globalThis);

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

@@ -1,4 +1,4 @@
-(function () {
+(function (global) {
 'use strict';
 
 var flEmit = function (el, name, detail) {
@@ -125,6 +125,8 @@ return out;
 }
 
 function Tabs(root, opts) {
+
+if (root && root.tabsInstance) return root.tabsInstance;
 this.root = root;
 this.opts = opts || {};
 this.list = root.querySelector('[role="tablist"]');
@@ -225,18 +227,21 @@ self.select(tab, false);
 });
 };
 
-window.Tabs = Tabs;
+global.Tabs = Tabs;
 
 function init() {
 var nodes = document.querySelectorAll('[data-tabs]');
 for (var i = 0; i < nodes.length; i++) {
+
+if (nodes[i].tabsInstance) continue;
 nodes[i].tabsInstance = new Tabs(nodes[i], {});
 }
 }
 
+if (typeof document === 'undefined') return;
 if (document.readyState === 'loading') {
 document.addEventListener('DOMContentLoaded', init);
 } else {
 init();
 }
-})();
+})(typeof window !== 'undefined' ? window : globalThis);