agentcss 0.0.0-stage → 0.11.3

package/adapters/presentation/to-doc.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+/*
+ * to-doc.js — deck → 核心契约文档
+ *
+ * ============================================================================
+ * 🔴 这个文件存在的全部意义
+ * ----------------------------------------------------------------------------
+ * 把「呈现语义」和「组件结构」**分开存放**：
+ *
+ *   deck.json   slide / layout / role  —— 呈现形态的事，本层负责
+ *   doc.json    节点 / 组件 / 插槽      —— 核心的事，核心负责
+ *
+ * 转换时，呈现语义被塞进每个节点的 `extensions.presentation`。
+ * ⇒ 核心校验器看到它：忽略（前向兼容，不判非法）
+ * ⇒ 本层看到它：知道这一页是第几页、这个节点是什么角色
+ *
+ * ⇒ **核心不需要知道 PPT 存在。** 这句话不是口号，是可以 grep 验证的：
+ *      grep -ril 'slide\|deck' 01-tokens 02-primitives 03-patterns 04-recipes
+ *    ⇒ 0 命中（由 05-audit/core-boundary-gate.py 守住）
+ *
+ * ============================================================================
+ * 用法
+ * ----------------------------------------------------------------------------
+ *   node adapters/presentation/to-doc.js deck.json [-o doc.json]
+ * ============================================================================
+ */
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+/**
+ * 读命令行开关。支持 `-o x` / `-o=x` / `--o=x` / `--o x` 四种写法。
+ * ⚠️ 第一版只认双横线 ⇒ `-o out.json` 被静默忽略，
+ *    结果文档被打印到 stdout 而**文件没写出来** ⇒ 下游 ENOENT（实测）。
+ *    **参数没生效却不报错**，是最难查的一类失败。
+ */
+function flag(name, def) {
+  for (var i = 0; i < process.argv.length; i++) {
+    var a = process.argv[i];
+    if (a === '-' + name || a === '--' + name) {
+      var v = process.argv[i + 1];
+      if (v !== undefined && v.charAt(0) !== '-') return v;
+      return def;
+    }
+    if (a.indexOf('-' + name + '=') === 0 || a.indexOf('--' + name + '=') === 0) {
+      return a.slice(a.indexOf('=') + 1);
+    }
+  }
+  return def;
+}
+
+function toDoc(deck) {
+  var nodes = {};
+  var root = [];
+
+  (deck.slides || []).forEach(function (slide, si) {
+    var slideId = 'slide-' + (slide.id || (si + 1));
+    var childIds = [];
+
+    (slide.nodes || []).forEach(function (n, ni) {
+      var id = n.id || (slideId + '-n' + (ni + 1));
+      var node = {
+        id: id,
+        kind: n.kind,
+        extensions: {
+          presentation: {
+            slide: si + 1,
+            slideId: slideId,
+            layout: slide.layout || null,
+            role: n.role || null
+          }
+        }
+      };
+      if (n.text !== undefined) node.text = n.text;
+      if (n.props) node.props = n.props;
+      if (n.children) node.children = n.children;
+      if (n.extensions) {
+        Object.keys(n.extensions).forEach(function (k) {
+          node.extensions[k] = n.extensions[k];
+        });
+      }
+      nodes[id] = node;
+      childIds.push(id);
+    });
+
+    nodes[slideId] = {
+      id: slideId,
+      kind: 'section',
+      children: childIds,
+      extensions: {
+        presentation: {
+          slide: si + 1,
+          layout: slide.layout || null,
+          title: slide.title || null
+        }
+      }
+    };
+    root.push(slideId);
+  });
+
+  return {
+    schemaVersion: '1.0.0',
+    profile: 'standard',
+    root: root,
+    nodes: nodes,
+    extensions: {
+      presentation: {
+        adapter: 'presentation',
+        adapterVersion: '1.0.0',
+        deckTitle: deck.title || null,
+        slideCount: (deck.slides || []).length
+      }
+    }
+  };
+}
+
+function main() {
+  var file = process.argv[2];
+  if (!file) {
+    process.stderr.write('用法：to-doc.js <deck.json> [-o doc.json]\n');
+    process.exit(1);
+  }
+  var deck = JSON.parse(fs.readFileSync(file, 'utf8'));
+  var doc = toDoc(deck);
+  var o = flag('o', null);
+  var txt = JSON.stringify(doc, null, 2) + '\n';
+  if (o) {
+    fs.writeFileSync(o, txt);
+    process.stdout.write('  已写出 ' + o + '（' + (deck.slides || []).length +
+      ' 页 / ' + Object.keys(doc.nodes).length + ' 个节点）\n');
+  } else {
+    process.stdout.write(txt);
+  }
+}
+
+if (require.main === module) main();
+module.exports = { toDoc: toDoc };

package/ai/START-HERE.md

@@ -0,0 +1,104 @@
+# AI 使用入口（frontend-lib）
+
+> **本文件只做导航，不复制契约与组件文档。** 要细节就去它指的地方看。
+
+## 0 · 先记住一件事
+
+**本库提供的是可选工程资产，不是所有 HTML/网站都必须遵守的统一规范。**
+
+- 组件不适用时，用别的实现 —— **不要为满足本库的实现偏好而牺牲任务结果**。
+- 修改已有网站时，**先看它原有的框架、组件和样式体系**，能沿用就沿用。
+- PPT、文档、邮件等其他输出形态**不自动继承**本库的网页布局规则。
+- 选组件看**实际实现、API、示例、适用场景**，不要只凭组件名称和成熟度字段判断。
+
+## 1 · 这个库提供什么
+
+| 能力 | 位置 |
+|---|---|
+| 设计令牌（色/间距/字号/圆角，明暗双主题，纯 CSS 无需 JS） | `01-tokens/tokens.css` |
+| 排版与页面骨架（**选配**，写在 `class="page"` 上才生效） | `01-tokens/typography.css`、`page.css` |
+| 组件（CSS 为主 + 可选 JS） | `02-primitives/`、`03-patterns/` |
+| 微行为核（Esc 关闭 / 焦点归还 / 方向键游走） | `01-tokens/behavior/` |
+| 页面级示例 | `04-recipes/`（清单见下节） |
+| 图表与可视化资产 | `09-assets/`（清单见下节） |
+| 机器可读契约 + 命令行 | `ai/*.json`、`ai/cli.js` |
+
+**没有的**（别找）：图标、React/Vue 组件（只有 CSS 类）、构建配置。
+
+> 🔴 下面这一段里的**数字与目录清单会漂移**（加一个组件就错一处），
+> 所以它由 `05-audit/fix-start-here.py` 生成；手改会被 `npm run gate` 判为漂移。
+> 它的值直接从 `ai/components.json` 与目录实际内容读出来 —— **不信上面的说法，信这个**。
+
+<!-- ==== AI-INVENTORY-BEGIN ==== -->
+- 组件 **35** 个（`beta` 4 · `stable` 31）
+- `04-recipes/`（页面级示例）：`analysis-report`（组合型研究报告：正文 + 辅助栏并排，窄屏退回单栏） · `data-showcase`（四种数据表达方式对照：我到底该用哪个） · `detail-page`（实体详情页骨架：字段齐全 / 部分缺失 / 无数据，三态同构（DOM 不变）） · `longform`（单栏长文排版与阅读节奏） · `report`（报告版式系统 v1：共享基础 + 三种版式取舍（杂志 / 科研技术 / 金融研究）） · `table`（专业数据表格：列级格式与单位，三种用途预设）
+- `09-assets/`（图表与可视化）：`bar`（柱状图，含 charter 13 图表规范的裁剪铁律） · `echarts-adapter`（把令牌喂给 ECharts，按需引入；本库不含 ECharts） · `model-viewer`（惰性加载的 3D 模型查看器） · `scientific-plot`（二维科学绘图：坐标轴 / 误差棒 / 置信区间带 / 对数轴） · `sparkline`（迷你趋势线，没有坐标轴的走势提示）
+<!-- ==== AI-INVENTORY-END ==== -->
+
+## 2 · 什么时候值得用 / 什么时候别用
+
+| 值得用 | 别用 |
+|---|---|
+| 从零写移动端页面，想要现成的暗色与无障碍基线 | 宿主已有成熟组件库（沿用它的） |
+| 要弹层/标签页/折叠面板且要求键盘可达 | 只要一两个样式，引整个库不划算 |
+| 单文件页不能外链 CSS（用 `04-recipes/tierA-tokens.css`） | 要 date-picker / calendar / upload 这类大而全控件 |
+
+## 3 · 怎么查
+
+| 想查什么 | 去哪 |
+|---|---|
+| 有哪些组件、多大、JS 是否必需 | 根目录 `START-HERE.md`（组件表由 `05-audit/fix-start-here.py` 生成，不会漂移） |
+| 组件清单与成熟度 | `node ai/cli.js components --maturity=stable` |
+| 令牌名与取值 | `node ai/cli.js tokens --mode=dark`、`node ai/cli.js tree`（分层视图） |
+| 组件真实长什么样 | 该组件目录下的 `demo.html` |
+| 页面怎么搭 | `04-recipes/` 下的示例 |
+| 令牌怎么改 | README「主题定制」（覆盖 CSS 变量，不需重新编译） |
+
+**类名即 API**（`.btn`、`.btn--primary`）。改样式改**令牌**，不要改类名，
+也不要在页面里重写组件选择器（会被更高特异性静默盖掉，成为死声明）。
+
+## 4 · 怎么判断一项能力是否经过验证
+
+| 信号 | 怎么看 |
+|---|---|
+| 成熟度 | `ai/components.json` 的 `maturity` 是**算出来的**（判据在 `ai/components.meta.json`），不是人写的 |
+| 有没有 demo | 组件目录下有 `demo.html` 就能直接跑起来对照 |
+| 有没有门禁守 | `05-audit/check-all.sh`（`npm run gate`）一次跑全，逐项打印 `PASS`/`FAIL`/`SKIP` |
+| 浏览器支持 | README「浏览器支持」表：桌面 Chrome/Edge/Firefox 已验证；**iOS/Android WebView 未在真机验证** |
+
+⚠️ **未在真机验证的项就是没验证**，不要替它打包票。
+
+## 5 · 什么时候应当沿用宿主项目现有技术
+
+- 宿主已有设计系统 / 组件库 ⇒ 用它的，本库只在确实缺一块时补。
+- 宿主已有构建与样式方案 ⇒ 不要为引入本库改它的构建。
+- 宿主页面既有布局能达成目标 ⇒ 改它的局部，不要套本库的页面骨架。
+- 输出形态不是网页（PPT / 文档 / 邮件）⇒ 本库的网页布局规则**不适用**。
+
+## 6 · 怎么跑已有检查
+
+```bash
+npm ci                 # 按锁文件安装（首次）
+npm test               # 单元测试
+npm run test:types     # 类型契约：正例必过 + 反例必挂
+npm run gate:fast      # 静态检查（约 45 秒，改代码时跑）
+npm run gate           # 全量检查（含浏览器，提交前跑）
+node ai/cli.js check <doc.json>   # 校验契约文档（读 JSON，不解析原始 HTML）
+```
+
+改动本库**自身**时的分层（决定该动哪一层）：
+
+| 层 | 文件 | 性质 |
+|---|---|---|
+| 不变式 | `docs/INVARIANT.md` | 客观事实，有门禁守边界 |
+| 契约 | `ai/*.json` | 版本化约定 |
+| 建议 | `docs/GUIDANCE.md` | 工作建议，可整份推翻 |
+
+> `docs/GUIDANCE.md` 里「贴进 system prompt 的极简版」的适用范围是
+> **维护 frontend-lib 自身或严格按本库范式写页面**，不是所有 HTML 任务的通用规则。
+
+## 7 · 三句话版本
+
+1. 这是**可选**资产；不适用就用别的，别硬套。
+2. 查组件去根目录 `START-HERE.md` 和组件自己的 `demo.html`，别猜。
+3. 改样式改令牌、保留类名；提交前跑 `npm run gate`。

package/ai/behaviors.json

@@ -0,0 +1,380 @@
+{
+  "_comment": "行为覆盖矩阵：哪些组件必须有哪种行为。四种状态：core=已收编到核（门禁核实用了核）/ manual=有手写实现但未收编（必须写现状）/ gap=应当有但根本没实现（必须写理由，计入缺口预算）/ n/a=不适用（必须写理由）。⚠️ 不登记 = 红：不许靠省略跳过。manual 与 gap 的数量受 budget 棘轮约束，只能降不能升。",
+  "version": "0.6.2",
+  "behaviors": {
+    "dismissable": {
+      "coreFile": "01-tokens/behavior/dismissable.js",
+      "gate": "05-audit/dismissable-check.js",
+      "fn": "flDismissable",
+      "meaning": "Esc 关闭 + 点击浮层之外关闭"
+    },
+    "focus-return": {
+      "coreFile": "01-tokens/behavior/focus-return.js",
+      "gate": "05-audit/focus-return-check.js",
+      "fn": "flFocusReturn",
+      "meaning": "记住打开时的焦点，关闭时还回去"
+    },
+    "roving": {
+      "coreFile": "01-tokens/behavior/roving.js",
+      "gate": "05-audit/roving-check.js",
+      "fn": "flRoving",
+      "meaning": "方向键在一组项里移动 DOM 焦点（roving tabindex）"
+    },
+    "typeahead": {
+      "coreFile": "01-tokens/behavior/typeahead.js",
+      "gate": "05-audit/typeahead-check.js",
+      "fn": "flTypeahead",
+      "meaning": "打字母/汉字跳到匹配项（不是过滤）"
+    }
+  },
+  "budget": {
+    "manual": 2,
+    "gap": 2
+  },
+  "matrix": {
+    "dismissable": {
+      "combobox": [
+        "core",
+        "0.8.8 收编：为此给核加了**返回值语义**（onDismiss 返回 false ⇒ 核不preventDefault/stopPropagation），才能表达本组件的三级 Esc：① 关列表 ② 清输入 ③ 放弃（不干预，Esc 继续传给外层）。契约门禁「Esc 先关列表再清输入」实测通过。"
+      ],
+      "date-range": [
+        "n/a",
+        "不是浮层：内联表单（两个日期输入 + 预设 + 错误提示），没有打开/关闭状态"
+      ],
+      "popover": [
+        "core",
+        ""
+      ],
+      "select": [
+        "core",
+        "0.8.6 收编：删掉手写的 document click（冒泡阶段判定）与 keydown 里的 Esc 分支；Esc 的 stopPropagation（只关最内层）由核统一承担"
+      ],
+      "accordion": [
+        "n/a",
+        "展开/收起是内容显隐，没有'关闭'语义；Esc 不参与"
+      ],
+      "drawer": [
+        "manual",
+        "0.8.6 评估后**决定不收编**：drawer 已经是**模态**弹层，它的 dismissable 只含 Esc；点遮罩关闭是它自己的语义（overlay 负责遮罩）。核的 onDocClick 会把「点遮罩」当成 outside 触发，而 drawer 想忽略非Esc 的关闭原因 ⇒ 需要给核加\"忽略 outside\"的开关，属于改核而不是接线。暂不做。"
+      ],
+      "dropdown": [
+        "core",
+        ""
+      ],
+      "flip": [
+        "n/a",
+        "纯过渡工具（FLIP 动画），没有浮层"
+      ],
+      "toc": [
+        "n/a",
+        "目录导航，纯链接跳转，没有浮层"
+      ],
+      "nav": [
+        "core",
+        "0.11.2 收编：抽屉的「Esc 关闭」直接走核。⚠️ 遮罩**不能**写进 inside —— 写进去就等于声明\"点遮罩算内部\"，那一句\"点遮罩关闭\"的注释会立刻变成谎话（实测过，关不掉）"
+      ],
+      "overlay": [
+        "manual",
+        "0.8.6 评估后**决定不收编**：dialog 是模态，**点外部不该关闭**（那是 modal 的定义）。核的 onDocClick 天然会处理 outside ⇒ 收编等于给 dialog 引入错误行为。overlay 只需 Esc 那一半，Esc 已在组件内正确实现（不依赖全局栈）。"
+      ],
+      "pagination": [
+        "n/a",
+        "分页控件常驻页面，没有浮层"
+      ],
+      "tabs": [
+        "n/a",
+        "面板切换不是浮层；Esc 无语义"
+      ],
+      "tooltip": [
+        "core",
+        "0.8.6 收编：手写的 document click（冒泡阶段）换成核的捕获阶段判定，顺带修掉\"点浮层内部也会关\""
+      ],
+      "tree": [
+        "n/a",
+        "常驻结构，没有'打开'状态；Esc 无语义"
+      ],
+      "bar": [
+        "n/a",
+        "图表：canvas 绘制，没有浮层"
+      ],
+      "echarts-adapter": [
+        "n/a",
+        "图表适配器：只做数据转换，没有浮层"
+      ],
+      "model-viewer": [
+        "n/a",
+        "三维查看器：canvas 交互，没有浮层"
+      ],
+      "sparkline": [
+        "n/a",
+        "迷你图：SVG 绘制，没有浮层"
+      ],
+      "scientific-plot": [
+        "n/a",
+        "科学绘图：SVG 绘制，没有浮层"
+      ],
+      "reveal": [
+        "n/a",
+        "不是浮层：入场由 IntersectionObserver 触发，没有打开/关闭状态"
+      ]
+    },
+    "focus-return": {
+      "combobox": [
+        "n/a",
+        "焦点从未离开输入框，无所谓归位"
+      ],
+      "date-range": [
+        "n/a",
+        "焦点一直在日期输入上"
+      ],
+      "popover": [
+        "core",
+        ""
+      ],
+      "select": [
+        "core",
+        "0.8.6 收编：open() 里 fr.save()、close() 里 fr.restore()（close(false) 的 Tab 场景不夺焦点，语义正好对上核的「记了才还」）"
+      ],
+      "accordion": [
+        "n/a",
+        "焦点一直在标题按钮上"
+      ],
+      "drawer": [
+        "core",
+        ""
+      ],
+      "dropdown": [
+        "core",
+        "0.8.6 收编：open() 里 fr.save()、close() 里 fr.restore()，替掉手写的 btn.focus() + document.contains 判存活"
+      ],
+      "flip": [
+        "n/a",
+        "动画工具，不涉及焦点"
+      ],
+      "toc": [
+        "n/a",
+        "链接跳转，焦点随链接走"
+      ],
+      "nav": [
+        "core",
+        "0.11.2 收编：焦点回给汉堡按钮。fallback 也指向汉堡 —— 抽屉是在它自己内部关掉的，此时\"打开前的焦点\"可能已经不可见（变宽自关路径）"
+      ],
+      "overlay": [
+        "core",
+        "0.8.6 收编并修掉真 bug：原来条件是 focusIsMine && ...，而 focusIsMine 在本文件里不存在 ⇒ 恒假 ⇒ 焦点从来没还过（门禁「关闭后焦点归位」一直靠这条假绿过关，反向控制确认判据有牙）"
+      ],
+      "pagination": [
+        "n/a",
+        "焦点常驻页码按钮"
+      ],
+      "tabs": [
+        "n/a",
+        "焦点一直在 tab 组内"
+      ],
+      "tooltip": [
+        "core",
+        "0.8.6 收编：show() 里fr.save() 记焦点、Esc 关闭时 restore()，不再手写 el.focus()（手写版在触发元素已被移除时 focus 一个不存在的元素）"
+      ],
+      "tree": [
+        "n/a",
+        "焦点一直在树内"
+      ],
+      "bar": [
+        "n/a",
+        "图表不涉及焦点"
+      ],
+      "echarts-adapter": [
+        "n/a",
+        "图表适配器不涉及焦点"
+      ],
+      "model-viewer": [
+        "n/a",
+        "三维查看器：canvas 交互，不涉及这组浮层焦点"
+      ],
+      "sparkline": [
+        "n/a",
+        "迷你图不涉及焦点"
+      ],
+      "scientific-plot": [
+        "n/a",
+        "科学绘图不涉及焦点"
+      ],
+      "reveal": [
+        "n/a",
+        "不改焦点、不接管键盘"
+      ]
+    },
+    "roving": {
+      "combobox": [
+        "n/a",
+        "aria-activedescendant 模式：焦点常驻 input，核靠 e.target 判断当前项 ⇒ 收不到"
+      ],
+      "date-range": [
+        "n/a",
+        "没有'一组项'"
+      ],
+      "popover": [
+        "n/a",
+        "浮层里没有项的集合"
+      ],
+      "select": [
+        "n/a",
+        "aria-activedescendant 模式：焦点常驻按钮"
+      ],
+      "accordion": [
+        "gap",
+        "APG 把方向键列为**可选**增强，本库未实现；要做就应走 roving 核，不该再手写一份"
+      ],
+      "drawer": [
+        "n/a",
+        "焦点陷阱（Tab 在首尾间循环）不是方向键游走"
+      ],
+      "dropdown": [
+        "core",
+        "tabindex:false —— APG 菜单的菜单项按规范全部 -1，核只接管步进"
+      ],
+      "flip": [
+        "n/a",
+        "动画工具，没有项集合"
+      ],
+      "toc": [
+        "n/a",
+        "目录是链接列表，按 Tab 逐个走是正确行为"
+      ],
+      "nav": [
+        "n/a",
+        "导航是一列链接，按 Tab 逐个走是正确行为（同 toc）；APG 没有对导航列表要求方向键游走"
+      ],
+      "overlay": [
+        "n/a",
+        "焦点陷阱，不是方向键游走"
+      ],
+      "pagination": [
+        "n/a",
+        "←→/Home·End 是**翻页命令**，不是在一组项里移动焦点"
+      ],
+      "tabs": [
+        "core",
+        ""
+      ],
+      "tooltip": [
+        "n/a",
+        "没有项集合"
+      ],
+      "tree": [
+        "core",
+        ""
+      ],
+      "bar": [
+        "n/a",
+        "图表没有可聚焦的项集合"
+      ],
+      "echarts-adapter": [
+        "n/a",
+        "图表适配器没有项集合"
+      ],
+      "model-viewer": [
+        "n/a",
+        "方向键是**相机平移**（OrbitControls），不是 UI 项游走"
+      ],
+      "sparkline": [
+        "n/a",
+        "迷你图没有项集合"
+      ],
+      "scientific-plot": [
+        "n/a",
+        "科学绘图的坐标轴/刻度不是可游走的 UI 项集合"
+      ],
+      "reveal": [
+        "n/a",
+        "不是复合控件：没有一组可聚焦项要在其间移动"
+      ]
+    },
+    "typeahead": {
+      "combobox": [
+        "n/a",
+        "有输入框，**打字即过滤**；用 typeahead 会每打一个字就把焦点拽走"
+      ],
+      "date-range": [
+        "n/a",
+        "没有候选项集合"
+      ],
+      "popover": [
+        "n/a",
+        "没有候选项集合"
+      ],
+      "select": [
+        "core",
+        ""
+      ],
+      "accordion": [
+        "n/a",
+        "标题数量少，APG 未要求"
+      ],
+      "drawer": [
+        "n/a",
+        "没有候选项集合"
+      ],
+      "dropdown": [
+        "gap",
+        "APG 菜单支持'按首字母跳到菜单项'（可选增强），本库未实现；要做就走 typeahead 核"
+      ],
+      "flip": [
+        "n/a",
+        "动画工具"
+      ],
+      "toc": [
+        "n/a",
+        "目录是链接列表，浏览器自带链接查找"
+      ],
+      "nav": [
+        "n/a",
+        "导航列表没有候选项集合，也没有\"打首字母跳项\"的契约；浏览器自带链接查找"
+      ],
+      "overlay": [
+        "n/a",
+        "没有候选项集合"
+      ],
+      "pagination": [
+        "n/a",
+        "页码是数字，不适用首字母跳转"
+      ],
+      "tabs": [
+        "n/a",
+        "APG Tabs 未要求 typeahead"
+      ],
+      "tooltip": [
+        "n/a",
+        "没有候选项集合"
+      ],
+      "tree": [
+        "core",
+        ""
+      ],
+      "bar": [
+        "n/a",
+        "图表没有候选项集合"
+      ],
+      "echarts-adapter": [
+        "n/a",
+        "图表适配器没有候选项集合"
+      ],
+      "model-viewer": [
+        "n/a",
+        "没有候选项集合"
+      ],
+      "sparkline": [
+        "n/a",
+        "迷你图没有候选项集合"
+      ],
+      "scientific-plot": [
+        "n/a",
+        "科学绘图没有候选项集合"
+      ],
+      "reveal": [
+        "n/a",
+        "不是复合控件：没有可键入定位的集合"
+      ]
+    }
+  }
+}

package/ai/behaviors.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://frontend-lib.dev/ai/behaviors.schema.json",
+  "title": "frontend-lib 行为覆盖矩阵",
+  "$comment": [
+    "描述 ai/behaviors.json 的形状：**哪些组件必须有哪种微行为**。",
+    "",
+    "🔴 为什么这份表要存在：四个微行为核抽完之后，『谁还没收编』『谁不适用』",
+    "   只写在人的脑子里 ⇒ 『不适用』和『忘了做』看起来一模一样。",
+    "",
+    "🔴 四种状态：",
+    "   core   已收编到核（门禁会去源码里核实真的用了核）",
+    "   manual 有手写实现但未收编（必须写现状）",
+    "   gap    应当有但根本没实现（必须写理由，计入缺口预算）",
+    "   n/a    不适用（必须写理由）",
+    "",
+    "⚠️ 不登记 = 门禁红：不许靠省略跳过。",
+    "⚠️ manual / gap 的数量受 budget 棘轮约束，只能降、不能升。",
+    "",
+    "⚠️ 本 schema 只用了 ai/validate.js 白名单里的关键字（propertyNames 不在",
+    "   白名单里 ⇒ 不能用；键名合法性由 behavior-matrix-gate.py 的第 ⑥ 条守）。"
+  ],
+  "type": "object",
+  "required": ["version", "behaviors", "budget", "matrix"],
+  "properties": {
+    "version": { "type": "string" },
+    "behaviors": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["coreFile", "gate", "fn", "meaning"],
+        "properties": {
+          "coreFile": { "type": "string" },
+          "gate": { "type": "string" },
+          "fn": { "type": "string", "pattern": "^fl[A-Z]" },
+          "meaning": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "required": ["manual", "gap"],
+      "properties": {
+        "manual": { "type": "integer", "minimum": 0 },
+        "gap": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "matrix": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}