agentcss 0.0.0-stage → 0.11.2

package/START-HERE.md

@@ -0,0 +1,164 @@
+# 从这里开始
+
+> **这个文件是给你用的，不是给我写的。**
+> 目标：下次要用这个库，**照着下面抄，不用重新摸索**。
+
+---
+
+## 三步
+
+### 第 1 步：判断你在哪一档
+
+| 你的情况 | 走哪条 | 需要多少 |
+|---|---|---|
+| **某项目 / 单文件页**（不能外链 CSS、不能构建）| **A** | 令牌 13.8 KB + 你要的那几个组件 |
+| **普通静态站**（能引 CSS、不能构建）| **B** | `<link>` 引 tokens + components |
+| **React / Vite 等** | **C** | 先读下面「C 档的额外说明」|
+
+### 第 2 步：抄令牌（**必做，三档都要**）
+
+| 档 | 抄什么 | 怎么抄 |
+|---|---|---|
+| **A** | `04-recipes/tierA-tokens.css` | 整份粘进 `<style>` |
+| **B / C** | `01-tokens/tokens.css` + `01-tokens/typography.css` | 两个 `<link>` |
+
+> ⚠️ **A 档那份是从 `tokens.css` 自动抽出来的**（`make-tiersnippet.py`），
+> 所以两边不会不一致。**不要手抄** —— 手抄迟早漂移。
+
+### 第 3 步：只抄你真正要用的组件
+
+**不要整个库都搬。** 下面是实测的每个组件多大：
+
+🔴 **带 `JS` 的组件要连 JS 一起抄** —— 那个 JS 是**行为契约**
+（键盘、焦点、ARIA），**去掉它组件就"看起来能用其实不能用"**。
+
+| 组件 | 文件 | 行数 | JS | 什么时候要 |
+|---|---|---|---|---|
+| 按钮 | `02-primitives/button/button.css` | 353 | — | 几乎总要 |
+| 输入框 | `02-primitives/input/input.css` | 239 | — | 有表单就要 |
+| 标签 / 徽章 | `02-primitives/badge/badge.css` | 141 | — | 有状态标记就要（"已披露""停牌"） |
+| 卡片 | `02-primitives/card/card.css` | 246 | — | 有分组内容就要 |
+| 单选 / 多选 | `02-primitives/choice/choice.css` | 395 | — | 单选 / 多选就要 |
+| 下拉选择 | `02-primitives/select/select.css` | 151 | **必需 549** (`select.js`) | 原生 select 的外观或交互不够用就要 |
+| 可搜索选择 | `02-primitives/combobox/combobox.css` | 223 | **必需 485** (`combobox.js`) | 选项多到要搜索，或要选多个并留成标签就要 |
+| 开关 | `02-primitives/switch/switch.css` | 370 | — | 有"立即生效的设置"就要 |
+| 分隔线 | `02-primitives/separator/separator.css` | 73 | — | 要分开内容块就要 |
+| 加载骨架 | `02-primitives/skeleton/skeleton.css` | 96 | — | 数据还没到、先把版式占住就要 |
+| 进度条 / 环 | `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`) | 长表单分段就要 |
+| 动作菜单（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/tree/tree.css` | 113 | **必需 456** (`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/content/content.css` | 286 | — | 写文档 / 长文就要 |
+| reveal | `03-patterns/reveal/reveal.css` | 93 | 可选 172 (`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 | — |  |
+| table | `04-recipes/table/table.css` | 372 | — |  |
+| bar | `09-assets/bar/bar.css` | 166 | **必需 320** (`bar.js`) |  |
+| model-viewer | `09-assets/model-viewer/model-viewer.css` | 143 | **必需 423** (`model-viewer.js`) |  |
+| scientific-plot | `09-assets/scientific-plot/scientific-plot.css` | 141 | **必需 610** (`scientific-plot.js`) |  |
+| sparkline | `09-assets/sparkline/sparkline.css` | 158 | **必需 508** (`sparkline.js`) |  |
+
+### 🔴 这些组件的 JS 是**必需的**（不是增强）
+
+它们的 JS 承担**行为契约**：键盘、ARIA、焦点。只抄 CSS 会得到"看起来能用其实不能用"的组件。
+
+| 组件 | JS | JS 里实测承担的机制 |
+|---|---|---|
+| 下拉选择 | `select.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 可搜索选择 | `combobox.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 浮层气泡 | `popover.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 日期区间 | `date-range.js` | 键盘 — · ARIA ✓ · 焦点 ✓ |
+| 标签页 | `tabs.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 折叠面板 | `accordion.js` | 键盘 ✓ · ARIA ✓ · 焦点 — |
+| 动作菜单 | `dropdown.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 文字提示 | `tooltip.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 分页 | `pagination.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 树形 | `tree.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 侧边抽屉 | `drawer.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 弹窗 / 吐司 | `overlay.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| 导航 / 目录 | `nav.js` | 键盘 ✓ · ARIA ✓ · 焦点 ✓ |
+| bar | `bar.js` | 键盘 — · ARIA ✓ · 焦点 — |
+| model-viewer | `model-viewer.js` | 键盘 — · ARIA — · 焦点 — |
+| scientific-plot | `scientific-plot.js` | 键盘 — · ARIA ✓ · 焦点 — |
+| sparkline | `sparkline.js` | 键盘 — · ARIA ✓ · 焦点 — |
+
+**已经人工验证过后果的三条**（其余的按上表推断，不要凭印象写后果）：
+
+- 标签页只抄 CSS：方向键不切面板 · Tab 会逐个穿过所有 tab
+- 折叠面板只抄 CSS：Enter / Space 不响应 · 面板的 `role="region"` 缺失
+- 弹窗 / 吐司只抄 CSS：**没有焦点陷阱** · Esc 不关 · 读屏不播报
+
+> `flip.js` / `toc.js` 是**可选增强**（动画、目录生成），
+> 它们的 CSS 本身是纯 CSS —— 不抄那两个 JS，组件照样能用。
+
+
+### 现成页面（整页抄，不是零件）
+
+| 示例 | 目录 | 它示范什么 |
+|---|---|---|
+| `analysis-report/` | `04-recipes/analysis-report/` | 组合型研究报告：正文 + 辅助栏并排，窄屏退回单栏 |
+| `data-showcase/` | `04-recipes/data-showcase/` | 四种数据表达方式对照：我到底该用哪个 |
+| `detail-page/` | `04-recipes/detail-page/` | 实体详情页骨架：字段齐全 / 部分缺失 / 无数据，三态同构（DOM 不变） |
+| `longform/` | `04-recipes/longform/` | 单栏长文排版与阅读节奏 |
+| `report/` | `04-recipes/report/` | 报告版式系统 v1：共享基础 + 三种版式取舍（杂志 / 科研技术 / 金融研究） |
+| `table/` | `04-recipes/table/` | 专业数据表格：列级格式与单位，三种用途预设 |
+
+## 抄完先做这三件事
+
+1. **看效果** —— 每个组件目录下有 `demo.html`，抄完对照着比
+2. **跑一遍无障碍** —— 浏览器控制台里（或用 axe）确认对比度达标
+3. **别改类名** —— 类名是 API（`.btn` `.btn--primary` `.field__input`），
+   改名等于换组件。**要改样式就改令牌**，全库会一起变
+
+---
+
+## C 档（React / Vite）的额外说明
+
+**目前没有构建配置。** 这个库是**零依赖、零构建**的纯 CSS + ES5 JS，
+所以在 Vite 里直接 `import './tokens.css'` 就能用，不需要任何额外配置。
+
+**如果你要的是 React 组件（`<Button />` 这样的），这个库现在没有** ——
+它给的是 CSS 类，不是组件。**这不是缺陷，是范围**：
+CSS 类跨框架通用，React 组件会绑死框架。
+
+---
+
+## 一句话记住
+
+> **抄 `tierA-tokens.css`（A 档）或 `tokens.css`（B/C 档）→ 再抄你要的那几个 CSS → 保留类名。**
+
+---
+
+## 你可能还想找的（有 / 没有，一次说清）
+
+> 🔴 这一节以前把徽章写成「没有」，而同一份文件的第 39 行就列着它 ——
+> 自己跟自己打架，比"漏写一项"更误导人。
+> 现在：**凡是上面组件表里有的，这里一律不再说没有。**
+
+| 你可能想要 | 有没有 |
+|---|---|
+| 徽章 | ✅ 有 —— `02-primitives/badge/`，见上面组件表 |
+| 数据表格 | ⚠️ 有现成页面，不是库级组件 —— 抄 `04-recipes/table/`（三种用途预设：财务 / 学术 / 统计）|
+| 指标块 / KPI 卡 | ❌ 没有专门组件 —— 用 `card` + 排版令牌自己搭，几分钟的事 |
+| 图标 | ❌ 本库不内置任何图标（`09-assets/` 下没有图标目录）—— 需要就自己内联 SVG，规格见 `09-assets/README.md` |
+| React / Vue 组件 | ❌ 只有 CSS 类（原因见上面「C 档」）|
+| 暗色模式 | ✅ 有，抄令牌就自带 |
+| 中文排版（i18n）| ✅ 有度量令牌，四语言实测过 |
+
+**没有就是没有。** 早知道比晚知道省时间。
+
+> 每一行的「有 / 没有」都是对着目录与契约数出来的。
+> 新增组件后请跑 `python 05-audit/fix-start-here.py` 重生成上面的表，
+> 再人工对一遍这一节 —— 脚本只管表，管不了散文。

package/SUPPORT.md

@@ -0,0 +1,109 @@
+# 浏览器支持矩阵
+
+> ⭐ 这份文件的作用是**诚实**。
+> 定位里写了「移动 Web」，就必须说清楚**哪些是验证过的、哪些没有**。
+> 没验证的不要写成支持的。
+>
+> 🔴 2026-10-09 修订说明（外部评审实测）：
+>   这一页以前写着「桌面 Firefox ✅ 已验证」和「自动化跑的是桌面 Firefox」——
+>   **两句都是假的**。当时的统一启动器只会找 Chromium，
+>   Firefox 从来没被启动过一次。
+>   ⇒ 这比"没验证"更糟：它给了一个**错误的**证据来源，
+>     读者会以为"至少 Firefox 跑过了"。
+>   现在引擎是真的切换了，并且每个作业都要**自己报 UA** 自证（见下）。
+
+## 状态定义
+
+| 标记 | 含义 |
+|---|---|
+| ✅ 已验证 | 有自动化检查覆盖，且**跑的就是这个引擎**（有 UA 证据） |
+| ⚠️ 部分验证 | 只覆盖了部分功能或部分视口 |
+| ❌ 未验证 | **没有在真实环境跑过** |
+
+---
+
+## 自动化覆盖的环境
+
+证据文件：`10-review/engine-evidence.json`（由 `05-audit/engine-gate.js` 生成，可复跑）。
+
+| 平台 | 引擎 | 状态 | 覆盖内容 |
+|---|---|---|---|
+| 桌面 | Chromium | ✅ | 全部组件契约、暗色对比度、响应式三档、视觉回归 |
+| 桌面 | WebKit | ✅ | nightly 矩阵的组件契约（select / combobox / date-range / overlay / tree / dropdown / popover / tooltip） |
+| 桌面 | Firefox | ⚠️ | 矩阵里**已声明并自证**，但本机/CI 需要先 `npx playwright install firefox`；没装时门禁显式 SKIP，不假装通过 |
+
+### 🔴 怎么知道"跑的真的是这个引擎"
+
+光有 `matrix.engine` 不够 —— 它以前只用在 `npx playwright install` 那一步，
+测试启动器根本没收到 ⇒ 三个作业跑的都是 Chromium。
+所以现在有两道独立的证明：
+
+1. **每个作业自证**：`FL_ENGINE=… node 05-audit/engine-probe.js`
+   站起来报一次自己的 UA，并校验 UA 属于声明的引擎族。
+   （⚠️ Chromium 的 UA 里**也含** `AppleWebKit` ⇒ 只判子串会把 Chromium 认成 WebKit，
+   判据必须同时排除 `Chrome/` 与 `HeadlessChrome`。）
+2. **矩阵整体自证**：`05-audit/engine-gate.js` 逐个引擎启动，
+   要求跑起来的引擎之间 **UA 两两不同** ⇒ 证明不是"同一个浏览器跑了三遍"。
+
+装不上某个引擎时是 **SKIP** 而不是"通过"
+⇒ 缺浏览器是环境问题，但**不许**被当成"矩阵没问题"。
+
+### 门禁数量
+
+不写死数字 —— 它由 `doc-facts-gate.py` 从 `05-audit/check-all.sh` **按名单**算，
+文档里写错会被判红。查当前数字：
+
+```
+python3 05-audit/doc-facts-gate.py
+```
+
+⚠️ **不要用 `grep -c 'run "'` 去数**：那会给出 **99** 这种偏小的数。
+原因是 `check-all.sh` 里有 `for g in …` 循环（里面的 `run "$g"` 是缩进的、名字是变量，
+grep 一条都数不到），还有 `skip "…"`（这台机器跑不了的门禁，也是注册数的一部分）。
+`doc-facts-gate.py` 会展开循环、把 `run` / `run_report` / `skip` 三种登记方式
+按**名字去重**后计数 ⇒ **任何机器上都是同一个数**。
+
+---
+
+## 尚未验证的环境
+
+| 平台 | 引擎 | 状态 | 说明 |
+|---|---|---|---|
+| iOS | WKWebView | ❌ | **未在真机或模拟器验证** |
+| iOS | Safari | ❌ | 未在真机验证 |
+| Android | Android WebView | ❌ | **未在真机验证** |
+| Android | Chrome（移动版）| ⚠️ | 仅用**桌面**引擎模拟了移动视口，**非真机引擎** |
+
+⚠️ 桌面 WebKit 自动化（上面那个 ✅）**不等于** iOS WKWebView：
+真机上的软键盘、可视视口变化、安全区、`100vh`、页面回弹、VoiceOver
+都没有被上面任何一项覆盖。
+
+---
+
+## 已知风险（未验证带来的）
+
+1. **`:has()`** —— 已在 `theme-toggle` 里避免使用；其余用法需在 WebKit 上实测
+2. **`backdrop-filter`** —— Firefox 与旧 WebKit 行为不一致，用了 `@supports` 兜底
+3. **`conic-gradient`**（环形进度）—— Safari 15.4+ 才支持
+4. **滚动条样式** —— `::-webkit-scrollbar` 与 Firefox 的 `scrollbar-width` 是两套语法，组件里都写了
+5. **iOS 输入框的 `font-size < 16px` 会触发缩放** —— 输入类组件已避免
+
+## 已知限制（已验证存在，不是"待验证"）
+
+| 限制 | 说明 |
+|---|---|
+| **popover 没有碰撞翻转** | 浮层按声明的方向挂出（`end` 方向 = 锚点右侧），**不会**因为贴边而自动翻到另一侧。⇒ 锚点靠近视口右缘时 `end` 方向会溢出。使用者需要自己选方向，或把锚点放在有余量的位置。 |
+| **没有 codemod / 运行时废弃告警** | 废弃流程（`ai/deprecations.json`）只是**版本号承诺**：到期允许移除，但不会在运行时警告你还在用。要真拦截得自己在 CI 加 lint。 |
+| **弹层锁滚动只补流式内容** | 锁滚动时补偿加在 `body` 的 `padding-right` 上，`position: fixed` 的元素相对视口定位、管不到 ⇒ 页面里若有吸底条，需要自己用 `--overlay-scrollbar-width` 补（见 `03-patterns/overlay/README.md`）。这是当前方案的**已知取舍**，不是还没做。 |
+
+---
+
+## 打算怎么补
+
+优先级从高到低：
+
+1. **Android WebView 真机**（用户量最大）
+2. **iOS WKWebView**（`100vh` / 滚动 / 输入框是重灾区）
+3. popover 的碰撞翻转（上面"已知限制"第 1 条）
+
+⚠️ 在补齐之前，请勿把「移动 WebView 支持」当作已验证的能力对外承诺。

package/adapters/presentation/README.md

@@ -0,0 +1,113 @@
+# Presentation Adapter（呈现适配层）
+
+> **这一层刻意在核心库之外。**
+> 核心（`01-tokens` ~ `04-recipes`、`ai/`）里**没有**任何 slide / deck / page 的概念。
+
+---
+
+## 一、为什么 PPT 语义不进核心
+
+一次真实事故：用本库做 14 页 PPT，AI 反复局部修改后整体崩坏，
+人工修 1.5 小时仍未收口。
+
+复盘时最容易得出的结论是「核心库要懂 PPT」——**这个结论是错的**。
+
+理由：
+
+| 如果进核心 | 后果 |
+|---|---|
+| 核心要知道"一页是什么" | 核心就从「组件库」变成「演示文稿引擎」 |
+| 核心要知道"一页能放几个元素" | 这个数字每换一种呈现形态（报告 / 海报 / 长图）就不一样 |
+| 核心要处理"翻页" | 翻页跟组件没有任何关系 |
+
+⇒ **呈现形态是会变的，组件是不变的。把易变的和不变的绑在一起，两边都动不了。**
+
+真正该做的是：**让核心提供一个稳定底座，让呈现语义挂在外层。**
+
+---
+
+## 二、怎么挂：用 `extensions`
+
+核心契约 `ai/contract.schema.json` 给每个节点和整个文档留了 `extensions`：
+
+```json
+{
+  "id": "title-1",
+  "kind": "text",
+  "text": "季度复盘",
+  "extensions": {
+    "presentation": { "slide": 1, "role": "title" }
+  }
+}
+```
+
+关键性质：
+
+- **核心校验器看到 `extensions` 就忽略**，既不报错也不读取。
+  ⇒ 核心不需要知道 PPT 存在。
+- **本适配器读取 `extensions.presentation`**，做呈现特有的检查。
+- ⇒ 两边通过**数据**耦合，不通过**代码**耦合。
+
+这不是"为了优雅"，是为了**前向兼容**：
+
+> 一个旧版核心遇到 `extensions.presentation` 不会判文档非法；
+> 一个新版本核心也不会因为多了一种呈现形态就要改自己的 schema。
+
+---
+
+## 三、用法
+
+```bash
+# deck → 核心契约文档（丢掉呈现语义，剩下纯组件结构）
+node adapters/presentation/to-doc.js deck.json -o doc.json
+
+# 用核心校验器校验（它会忽略 extensions）
+node ai/cli.js check doc.json --profile=standard
+
+# 呈现特有的检查（每页元素数、标题层级、字号下限）
+node adapters/presentation/check.js deck.json
+```
+
+---
+
+## 四、这一层负责什么，不负责什么
+
+| 负责 | 不负责 |
+|---|---|
+| slide / deck 的语义 | 组件长什么样（核心的事） |
+| 每页元素数量、层级结构 | 颜色令牌（核心的事） |
+| 呈现形态特有的约束 | 无障碍（核心的事，且**任何形态下都要成立**） |
+| — | **"改一处全局，N 页是否跟着变"**（那是页面骨架的事：`01-tokens/page.css` + `shell` / `skel-lever` 两道门禁） |
+
+⚠️ **无障碍不因呈现形态而打折。** 一页 PPT 也是给人看的，
+对比度、焦点可见、键盘可达在任何形态下都要成立 —— 这是核心的事，
+本层不能为了"好看"把它绕过去。
+
+---
+
+## 五、这些检查有人跑吗
+
+🔴 曾经没有。`check.js` 的五条判据从写下到 0.4.2 之前，**一次都没被执行过** ——
+README 说有，实际没人跑。这是最隐蔽的一种假绿：它连"通过"报告都不产出。
+
+现在有 `05-audit/presentation-gate.py`（已接入 `check-all.sh`）：
+
+| 判据 | 怎么验 |
+|---|---|
+| 合规 deck 必须过 | `fixtures/deck-ok.json` ⇒ check.js exit 0 |
+| 违规 deck 必须红 | `fixtures/deck-bad.json` ⇒ exit ≠ 0 |
+| **五条判据各命中一次** | 少一条就红 ⇒ 判据被删/被改文案会立刻暴露 |
+| 两个真值源不漂移 | `check.js` 的 `MAX_PER_SLIDE` 必须等于 `deck.schema.json` 的 `nodes.maxItems` |
+| 门禁自己也会失效 | `--selftest`：把上限放宽到 999、去掉 `.slide-` 正则、把 schema 改成 8 ⇒ 门禁必须认出判据已失效 |
+
+自测：
+
+```bash
+python 05-audit/presentation-gate.py            # 正常跑
+python 05-audit/presentation-gate.py --selftest # 反向控制
+```
+
+## 六、如果以后要加别的形态
+
+照这个目录再加一个 `adapters/<形态>/`，同样用 `extensions.<形态>` 承载。
+**核心不需要改一行代码** —— 这就是它被分出来的全部意义。

package/adapters/presentation/check.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/*
+ * check.js — 呈现形态特有的检查（**不属于核心门禁**）
+ *
+ * ============================================================================
+ * 🔴 为什么这些检查不在核心里
+ * ----------------------------------------------------------------------------
+ * 下面每一条判据都只对一个**呈现形态**成立：
+ *   · 单页元素上限 12 —— 换成报告形态这个数就不对
+ *   · 版面必须已登记  —— 换成海报形态版面集合完全不同
+ *   · 每页必须有标题  —— 换成封面页就不该有
+ *
+ ⇒ 把它们写进核心 = 核心要跟着每一种形态改一次。
+   核心应该只管**任何形态下都成立**的事（对比度、焦点、键盘、令牌）。
+ *
+ * ============================================================================
+ * 判据
+ * ----------------------------------------------------------------------------
+ *   ① 版面必须已登记（deck.schema.json 的 layouts.registered）
+ *   ② 单页元素数 <= 12（超过必然溢出）
+ *   ③ 非封面页必须有 role=title 的节点
+ *   ④ 标题层级不跳级（有 subtitle 就必须先有 title）
+ *   ⑤ 不得出现"页面级 override"式表达（.slide-N xxx）—— 那是事故形态
+ * ============================================================================
+ */
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+var HERE = __dirname;
+var MAX_PER_SLIDE = 12;
+
+function main() {
+  var file = process.argv[2];
+  if (!file) {
+    process.stderr.write('用法：check.js <deck.json>\n');
+    process.exit(1);
+  }
+  var deck = JSON.parse(fs.readFileSync(file, 'utf8'));
+  var schema = JSON.parse(fs.readFileSync(path.join(HERE, 'deck.schema.json'), 'utf8'));
+  var registered = schema.layouts.registered;
+
+  var errs = [];
+  var warns = [];
+
+  (deck.slides || []).forEach(function (slide, i) {
+    var at = '第 ' + (i + 1) + ' 页';
+    var sid = slide.id || (i + 1);
+
+    // ① 版面已登记
+    if (slide.layout && registered.indexOf(slide.layout) < 0) {
+      errs.push(at + '：版面 ' + slide.layout + ' 未登记（已登记：' +
+        registered.join(' / ') + '）');
+    }
+    if (!slide.layout) {
+      warns.push(at + '：没有指定版面');
+    }
+
+    var nodes = slide.nodes || [];
+    // ② 单页元素上限
+    if (nodes.length > MAX_PER_SLIDE) {
+      errs.push(at + '：' + nodes.length + ' 个元素，超过上限 ' + MAX_PER_SLIDE +
+        ' ⇒ 必然溢出，溢出后只能靠加特异性去救，那是事故的开始');
+    }
+
+    // ③ 非封面/分隔页必须有标题
+    var roles = nodes.map(function (n) { return n.role; });
+    var isCover = slide.layout === 'title' || slide.layout === 'section-break';
+    if (!isCover && roles.indexOf('title') < 0 && !slide.title) {
+      errs.push(at + '：没有标题（既没有 slide.title，也没有 role=title 的节点）');
+    }
+
+    // ④ 层级不跳级
+    if (roles.indexOf('subtitle') >= 0 && roles.indexOf('title') < 0 && !slide.title) {
+      errs.push(at + '：有 subtitle 但没有 title ⇒ 层级跳级');
+    }
+
+    // ⑤ 页面级 override 式表达
+    var dump = JSON.stringify(slide);
+    if (/\.slide-/.test(dump) || /\.page-\d/.test(dump)) {
+      errs.push(at + '：出现了页面级选择器（.slide-N / .page-N）' +
+        ' ⇒ 这正是事故的形态，请改组件而不是改页面');
+    }
+  });
+
+  if (warns.length) {
+    process.stdout.write('  ⚠️ 提示：\n');
+    warns.forEach(function (w) { process.stdout.write('       ' + w + '\n'); });
+  }
+  if (errs.length) {
+    process.stdout.write('  [FAIL] 呈现检查：\n');
+    errs.forEach(function (e) { process.stdout.write('       ' + e + '\n'); });
+    process.exit(1);
+  }
+  process.stdout.write('  [OK] 呈现检查通过（' + (deck.slides || []).length + ' 页）\n');
+  process.exit(0);
+}
+
+if (require.main === module) main();
+module.exports = { MAX_PER_SLIDE: MAX_PER_SLIDE };

package/adapters/presentation/deck.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://frontend-lib.dev/adapters/presentation/deck.schema.json",
+  "title": "Presentation 形态：deck / slide 语义",
+  "$comment": [
+    "🔴 这份 schema **不属于核心契约**。",
+    "   核心（ai/contract.schema.json）里没有任何 slide / deck / page 的概念，",
+    "   这是故意的 —— 呈现形态会变，组件不变，绑在一起两边都动不了。",
+    "",
+    "本层把 slide/deck 语义挂在核心节点的 extensions.presentation 上：",
+    "   · 核心校验器看到 extensions 就忽略 ⇒ 核心不需要知道 PPT 存在",
+    "   · 本层读取它 ⇒ 做呈现特有的检查",
+    "⇒ 通过**数据**耦合，不通过**代码**耦合。"
+  ],
+  "type": "object",
+  "required": ["schemaVersion", "slides"],
+  "properties": {
+    "schemaVersion": { "type": "string" },
+    "title": { "type": "string" },
+    "slides": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/slide" }
+    },
+    "extensions": { "type": "object" }
+  },
+  "definitions": {
+    "slide": {
+      "type": "object",
+      "required": ["id", "nodes"],
+      "properties": {
+        "id": { "type": "string" },
+        "layout": {
+          "type": "string",
+          "$comment": "版面名。**只允许用已登记的版面** —— 自由发挥的版面无法被检查。"
+        },
+        "title": { "type": "string" },
+        "nodes": {
+          "type": "array",
+          "maxItems": 12,
+          "$comment": [
+            "单页元素上限。🔴 这不是审美建议，是可判的约束：",
+            "超过这个数，任何版面都放不下 ⇒ 必然会溢出 ⇒ 溢出后只能靠加特异性去救，",
+            "那就是事故的开始。"
+          ],
+          "items": { "$ref": "#/definitions/slideNode" }
+        },
+        "extensions": { "type": "object" }
+      }
+    },
+    "slideNode": {
+      "type": "object",
+      "required": ["id", "kind"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "type": "string" },
+        "text": { "type": "string" },
+        "props": { "type": "object" },
+        "children": { "type": "array", "items": { "type": "string" } },
+        "role": {
+          "type": "string",
+          "enum": ["title", "subtitle", "body", "caption", "media", "footer"],
+          "$comment": "在页内的语义角色。决定字号与层级，不决定具体色值（那是核心令牌的事）。"
+        },
+        "extensions": { "type": "object" }
+      }
+    }
+  },
+  "layouts": {
+    "$comment": "已登记版面（白名单）。需要新版面 ⇒ 先登记，再使用。",
+    "registered": ["title", "title-body", "two-col", "quote",
+                   "media-caption", "bullets", "section-break", "closing"]
+  }
+}