agentcss 0.11.2 → 0.11.4

package/CHANGELOG.md

@@ -14,7 +14,70 @@
 
 ## [Unreleased]
 
-（本轮无未发布改动 —— 0.11.2 的条目见下方。）
+（无）
+
+## [0.11.4] - 2026-10-29
+
+**使用者能摸到的改动只有一处**：`bar.draw` 的报错文案不再指向一个装包的人打不开的文档。
+其余是把交付面收紧一档 —— 随包文件从 274 降到 268，文档第一次有了可搜索的索引。
+
+### Added
+
+- **组件文档站** `guide/`：35 个组件各一页，外加一个可搜索的索引。
+  真值只有两处 —— `ai/components.json`（有哪些组件、什么档、成熟度）与
+  各组件的 `README.md`（内容）。页面里的示例链接、源文件链接都解析到仓库里
+  **真实存在**的路径，不是凭命名规则猜的。
+- **根 `index.html` 改为生成物**。此前它是手写的，于是 `reveal` /
+  `analysis-report` / `detail-page` / `longform` / `data-showcase` /
+  `scientific-plot` 六个页面**早就存在、索引里一个都没有**，而门禁全绿 ——
+  没有任何一道判据问过「索引覆盖了几页」。
+- 索引页末尾列出**只在本站有、不随包发布**的三个页面（iOS 真机验证、
+  组合页、React + Vite 示例）。它们此前只能靠知道路径才打得开。
+- `05-audit/gen-docs.py`（生成器）与 `05-audit/docs-site-gate.py`（判据：
+  产物是否为现算、每页链接能否落地、`lang` / 单一 `h1` / `main` / skip link /
+  无重复 id、不引任何外部资源）。
+- GitHub Pages 的构建作业在打包前先核一遍「入库的产物是不是现算的」。
+
+### Fixed
+
+- `bar.draw` 的错误消息、`bar.css` / `bar.js` / `echarts-adapter.js` /
+  `model-viewer.css` 的若干注释里写着**只有内部才有的文档编号**
+  （形如「NN 规范 · 第 N 条铁律」）。那些文件随包发给每一个使用者，
+  而那份文档不在仓库里 —— 读者只会看到一个打不开的引用。
+  全部改成自洽表述，规则本身留在原处。
+- 索引页漏页（同上）。
+- **文档站的页面框改回只有骨架一份**。第一版为了"顶栏整幅贴边"，
+  在文档站样式里把 `page.css` 给的页面框清零、另写了一套内边距 ——
+  结果改 `--sp-6` 时 35 个文档页一个都不动（页面照样写着 `class="page"`，
+  渲染出来也看不出差别）。现在页面框归骨架，顶栏放进框内。
+- 索引页的搜索键从 `data-k` 属性挪进 `<script type="application/json">`：
+  放在属性里会被读屏念出来，也会被"按结构扫 HTML"的判据当成真在用那些属性。
+- 索引页指向整页示例的两个链接带反斜杠（`data-showcase\demo.html`）：
+  浏览器会把 `\` 当 `/` 兜住，但任何链接检查都会判它跑出仓库。
+
+### Changed
+
+- `package.json` 的 `homepage` 指向文档站：npm 页面上的「Homepage」
+  现在直接到能读的文档，而不是仓库首页。
+- 随 `files` 白名单出去的内部台账（错误复盘 66 条、待办裁定、路线图、
+  发版操作说明、对标分析）全部移出仓库。它们解释的是「怎么做到的」，
+  不是「怎么用它」，而其中发版操作那一份还写着账号的安全配置。
+
+<!-- 0.11.4 的实测口径：`npm pack --dry-run` 268 个文件；
+     `guide/` 37 页（35 组件 + 索引 + 样式），链接检查 0 死链。 -->
+
+---
+
+## [0.11.3] - 2026-10-28
+
+**只改文档，不改任何代码。** 上一个版本打包进去的 README 安装段写着
+「registry 上没有可安装版本」——装下来的人第一眼就读到一句与事实相反的话。
+这一版把这句话改成事实。
+
+### Fixed
+
+- `README.md`「安装」段：改为 `npm install agentcss`（真实可用），
+  并把 GitHub Release 附件、`github:` 两条路径列为备选而非唯一。
 
 ## [0.11.2] - 2026-10-28
 
@@ -365,8 +428,8 @@ sparkline 迷你趋势）+ `rep--finance` 报告版式 + `Bar` 分部堆叠柱 +
   ② 快速重复触发时**同一属性并发 ≤ 1**（按属性计，不按动画对象总数 —— 一个切换本来就产生 2 个对象）；
   ③ `prefers-reduced-motion: reduce` 下**动画 0 个、opacity 恒为 1**。
 - 反向控制不是喂合成数据，而是**在真实页面注入 `*{transition:none}`** ⇒ 判据 ① 必须变红。
-- 实测结论：三条全过。**huxx 那条「动画进行中不要打断」我们不需要**
-  —— 它是给 JS 动画（会重启）说的，我们的 CSS transition 是 retarget。
+- 实测结论：三条全过。**「动画进行中不要打断」这条守卫不需要**
+  —— 它是给 JS 动画（会重启）说的，而 CSS transition 是 retarget。
   反过来加守卫会让离场元素"多亮一下"，已撤回。结论写进 `03-patterns/reveal/README.md`
   的负面结论区（含重开条件）。
 
@@ -427,7 +490,7 @@ sparkline 迷你趋势）+ `rep--finance` 报告版式 + `Bar` 分部堆叠柱 +
   的用法串统一到 `agentcss`；`package.json` 补上 `bin`（`agentcss ai …`
   终于能当命令用，此前只有 `node ai/cli.js`）。
 
-### Fixed · reveal 的白屏兜底（huxx 第 5 条落地）
+### Fixed · reveal 的白屏兜底
 
 - **真实缺陷**：`enable()` 先把 `data-reveal-ready` 打到 `<html>` 上，
   **再** `new IntersectionObserver`。构造函数一旦抛错（部分 WebView 有此
@@ -654,13 +717,13 @@ sparkline 迷你趋势）+ `rep--finance` 报告版式 + `Bar` 分部堆叠柱 +
 - **两个生成器写文件默认 CRLF**（`theme-sync` / `make-tiersnippet`）。
   D4 已经把全库统一成 LF，而生成器每跑一次就翻回 CRLF —— 两道工序互相拆台。
   已全部显式 `newline='
-'`（见 `ERRORS.md` E48）。
+'`。
 
 - **探针页的「复制结果」在手机上必然失败** —— 它只用 `navigator.clipboard`，
   而那个 API **只在安全上下文存在**（https / localhost / file://）。
   手机访问 `http://<内网地址>:端口` 时它是 `undefined` ⇒ 按钮直接弹"复制失败"。
-  我交付前的验证用的是 `file://` 与 `127.0.0.1` —— **两个都是安全上下文**，
-  于是测成了"成功"。⇒ 已登记 `ERRORS.md` E47。
+  交付前的验证若只用 `file://` 与 `127.0.0.1` —— **两个都是安全上下文** ——
+  就测不出这个问题。
   现在：主路径改成**同源 POST「发送到电脑」**（不碰剪贴板、不依赖安全上下文），
   剪贴板降为备用并补 `document.execCommand('copy')` 兜底；
   前两级都失败时用 `Range` **替用户全选**文本 —— 否则"长按复制"只会选中一个词，
@@ -982,19 +1045,19 @@ after:   47 +7 条单测 / 5 个核全覆盖 · 跑 0.7 秒
 | `dismissable` Esc 不再 stopPropagation | 1 条红 |
 | `roving` 的循环导航失效 | 2 条红 |
 
-### 🔴 写这个文件时我犯的错（ERRORS E40）
+### 🔴 这份契约文件写错过的地方
 
 **第一版测试是照想象写的**，凭空捏造了 API：
 `flEmitOn()`（emit 根本没这个）、`t.key('a')`（真名 `type()`）、
 `r.key({...})`（真名 `step(i,d)` / `rove(元素)`）⇒ 43 条里 21 条假失败。
 
-更糟的是**中途我在打补丁时越修越少**（43→22→16→14），
-因为用正则批量改代码、自己又引入新错误。**停下来实测真实行为才查清。**
+更糟的是**用正则批量打补丁会越修越少**（实测 43→22→16→14）：
+批量改代码的同时会引入新错误。**停下来实测真实行为才查清。**
 
 ⇒ 纪律：
 1. **测任何东西之前先读它的真实签名**（`sed -n '/^var flX/,/^  function/p'`）
 2. 批量正则改测试代码是**高危**的—— 改完必须先看数量变化是否符合预期
-3. 测试失败时**先怀疑自己的调用姿势**，而不是先怀疑被测代码
+3. 测试失败时**先核对调用姿势**，而不是先怀疑被测代码
 
 顺带记两个由实测才发现的真实契约（此前无人写过）：
 - `roving` 的 `axis` **默认 'x'** ⇒ 默认配置下 ArrowDown/Up **不响应**
@@ -1036,7 +1099,7 @@ JS 没有编译期检查，拼错的变量名静默为 `undefined`。门禁那
 | `drawer` | 模态弹层，只需 Esc；要核支持"忽略 outside"得**改核**而不是接线 |
 | `overlay` | dialog 是模态，**点外部不该关闭**；核天然处理 outside ⇒ 收编等于引入错误行为 |
 
-⇒ **「收编率」不是 KPI，行为正确才是**（ERRORS E37）。
+⇒ **「收编率」不是 KPI，行为正确才是**。
 
 ### 收编后的数字
 
@@ -1135,7 +1198,7 @@ stable 28（was 26） · beta 5（was 7）
 
 ## [0.8.2] - 2026-10-10
 
-外部评审（VIZ-REPORT-01）指出**图表与表格正确性**仅 5.0/10，指控四项。
+审查发现**图表与表格正确性**仅 5.0/10，指控四项。
 本轮逐条**先取证后修**，并新增**结果级判据**（读浏览器几何/计算值，
 而不是读 CSS 文本）。新增 `04-recipes/report` 报告版式系统 v1。
 
@@ -1278,15 +1341,10 @@ model-viewer / echarts-adapter），正文一个字没提；且正文是对话
 （"图标本体我拿不到，请给我"）。⇒ 改为面向使用者，
 目录清单与 AI 入口同源、由同一份脚本生成。
 
-**4 · 补上 `ERRORS.md`**
-
-收敛计划里写明"教训要写进 ERRORS.md"，而这个文件一直不存在。
-现在 14 条，每条「症状 → 根因 → 纠正规则」，规则都能照着执行。
-
-**5 · `docs/ROADMAP.md` 两处打架**
+**4 · 文档与发布白名单对齐**
 
-第一节 6 行写「待办 W3 / W7 / W8 / W9」，第三节里同样编号已标完成。
-⇒ 统一为「已完成（Wx）」，并在表下注明核对过一次。
+根级 `.md` 与 `docs/` 全部进了 npm `files` 白名单，并用 `npm pack --dry-run`
+实装确认 —— 此前 `START-HERE.md` 这类明确写着"给使用者看的"文件，其实没进包。
 
 ### 补上的两个洞（都是门禁漏扫，不是文档漏写）
 
@@ -1296,7 +1354,7 @@ model-viewer / echarts-adapter），正文一个字没提；且正文是对话
   名字与否定词之间必须有分隔符（`|` / ❌），避免误报普通句子。
 - **`release-gate` 不管文档有没有进包**：README 写着「`START-HERE.md`（根目录）
   是给人类复用者的三步清单」，而 npm 的 `files` 白名单里没有它。
-  已补判据，并把 `START-HERE.md` / `API.md` / `ERRORS.md` / `SUPPORT.md` /
+  已补判据，并把 `START-HERE.md` / `API.md` / `SUPPORT.md` /
   `CHANGELOG.md` / `docs/` 加进白名单 —— 已用 `npm pack --dry-run` 实装确认。
 
 ## [0.8.0] - 2026-10-10
@@ -1467,9 +1525,9 @@ model-viewer / echarts-adapter），正文一个字没提；且正文是对话
 
 ## [0.7.12] - 2026-10-10
 
-### Combobox：四条实例级缺陷（外部评审 N7–N10）
+### Combobox：四条实例级缺陷
 
-评审指出的问题都在**实例**层面 —— demo 页面上完全查不出来，
+这些问题都在**实例**层面 —— demo 页面上完全查不出来，
 所以新写了一道**自己造实例**的门禁（`combobox-instance-check.js`，15 条判据）。
 
 | 缺陷 | 症状 | 改法 |
@@ -1558,9 +1616,9 @@ model-viewer / echarts-adapter），正文一个字没提；且正文是对话
 
 ## [0.7.10] - 2026-10-09
 
-> 外部评审里 **Overlay 那组**（"弹层会不会弄坏宿主页面"）的整改。
+> **Overlay**（"弹层会不会弄坏宿主页面"）的整改。
 > ⚠️ 改的过程中撞见两件比原指控更严重的事，都记在本节：
->   ① 我第一版写的判据**量错了对象**，怎么改代码都不可能过；
+>   ① 最初那版判据**量错了对象**，怎么改代码都不可能过；
 >   ② 一直在用的 `scrollbar-gutter: stable` 其实是**按下葫芦浮起瓢**，
 >      实测推翻后换掉了。
 > 新增门禁 `overlay-host-check` + 常驻反向控制 `overlay-host-reverse`。
@@ -1930,7 +1988,7 @@ YAML 规范要求注释标记 `#` 必须与前面的内容由**空白**分隔。
 ### 改：文档与元数据
 
 - `docs/AI-CONTRACT.md` —— 补废弃登记册与基线的说明，并写明**诚实边界**：
-  我们没有 codemod、也没有运行时告警 ⇒ 这个"窗口"只是版本号承诺，不是技术阻断
+  本库没有 codemod、也没有运行时告警 ⇒ 这个"窗口"只是版本号承诺，不是技术阻断
 - `ai/deprecations.schema.json` —— 新 schema；已接进 `ai/cli.js validate`
   与 `05-audit/ai-layer-gate.js`（schema 份数 7 → 8）
   ⇒ 正例通过、5 个反例（kind 写错 / 版本号不是三段 / 缺 reason /
@@ -1993,7 +2051,7 @@ overlay · select · tooltip）。
 ⇒ 仓库里任何一处不相干的命中，都会让 4 条「正常内容应**不**被抓」被报成
 「**误报**了」。
 
-实测（本次收口撞上的）：我在更新日志里写了一个 `leak-scan` 明令禁止的**内部流程词**
+实测（本次收口撞上的）：更新日志里曾出现一个 `leak-scan` 明令禁止的**内部流程词**
 （`terms.PROCESS_WORDS` 里的那个，字面就不复述了 —— 写了它这道门禁会红）
 ⇒ 全库报 1 处 ⇒ 那 4 条样本集体被冤枉，而它们一条都没误报。
 ⚠️ 这种报告是**误导性**的：它会把人引去改一个根本没坏的判据。
@@ -2474,7 +2532,7 @@ root.addEventListener('change', fn);   // 写得很自然
 ### 加：微行为核 —— 同一件事不再写 N 份（M2 · 对标 Radix 的行为原语）
 
 Radix 把"关得掉 / 焦点归位 / 方向键游走 / 首字母跳转"做成**四个原语**，
-组件引用它们，而不是各自重写。我们此前是后者：
+组件引用它们，而不是各自重写。迁移前属于后者：
 
 | 行为 | 迁移前（14 个组件 JS 实测） |
 |---|---|
@@ -2614,14 +2672,14 @@ focus-return / roving / typeahead 三个核，以及 `ai/behaviors.json` 行为
 ### 加：`dist/` —— 源码与交付物分离（M1 · 对标 Pico / Open Props）
 
 实测：全库 CSS 原始 323.9 KB，**其中 207.5 KB 是注释（64%）**；
-`01-tokens/tokens.css` 源码版 gzip 15.8 KB ⇒ 使用者下载的是我们的推理过程。
+`01-tokens/tokens.css` 源码版 gzip 15.8 KB ⇒ 使用者下载到的是注释而不是样式。
 
 Pico 在 README 上按产物逐个公布体积；Open Props 的 CDN 清单区分源版与 min 版；
-Web Awesome 从 `dist/` 交付。三家都是 **src 可读、dist 可 ship**，只有我们把二者混成一个文件。
+Web Awesome 从 `dist/` 交付。三家都是 **src 可读、dist 可 ship**，区别只在这一点上。
 
-⭐ 更要紧的一条理由来自我们自己：`.gitignore` 里早就写着
+⭐ 更要紧的一条理由：`.gitignore` 里早就写着
 「内部工作文档不进仓库 —— 交付面只放提交物」（决策记录 / 复盘 / 作战计划三类目录全在名单里）。
-⇒ **这条纪律我们已经执行了，只是只对 markdown 执行了。** M1 把它扩到 CSS。
+⇒ **这条纪律对 markdown 已经生效，只是没扩到 CSS。** M1 把它扩到 CSS。
 
 - `dist/**/*.min.css`：去注释 + 压缩（`tokens` 15.8 KB → **2.1 KB**，省 86%）
 - `dist/**/*.css`：只去注释、保留格式（便于 diff / 阅读）
@@ -2789,7 +2847,7 @@ Web Awesome 从 `dist/` 交付。三家都是 **src 可读、dist 可 ship**，
 
 实测第三次栽在同一个坑上，这次是**运行器自己**：
 
-1. 我在**源仓库目录**手动起过一个 `http.server` 忘了关；
+1. 源仓库目录里手动起过一个 `http.server` 且没关；
 2. 随后在一个**克隆副本**里跑全量验收；
 3. 运行器探测到 8000 已通 ⇒ 打印「复用已在跑的服务」⇒
    100 多道浏览器门禁量的全是**源仓库**。

package/CONTRIBUTING.md

@@ -8,7 +8,7 @@ npm run gate           # 全量：含浏览器类
 npm run gate:fast      # 只跑静态层，不用装浏览器
 ```
 
-全量是 **177 道门禁**（本机约 10 分钟）。
+全量是 **179 道门禁**（本机约 10 分钟）。
 
 ⚠️ 上面的数字写在**代码块外**是有意的：`doc-facts-gate` 会核对
 「文档里的门禁数」与 `check-all.sh` 的真实注册数，而**代码块内的内容被豁免**