agentcss 0.25.3 → 0.25.4

package/CHANGELOG.md

@@ -16,6 +16,60 @@
 
 （无）
 
+## [0.25.4] - 2026-11-03
+
+**修订版：把「类型里看不见的那 8 个全局」补上，并让这件事以后有人管。
+不改组件行为、不改类名、不改令牌值。**
+
+### 修复：8 个挂在 `window` 上的对象没有类型（E297）
+
+源码里有 **24 个** `window.X =` / `global.X =`，`types/index.d.ts` 只声明了 **16 个**：
+
+| 缺的 | 后果 |
+|---|---|
+| `Theme` / `Chart` / `ChartAdapter` / `ModelViewer` | TS 项目里 `window.Theme.set('dark')` 直接报"属性不存在" |
+| `Bar` / `ScientificPlot` / `ShellNav` | 同上（审计报告没点到这三个） |
+| `Upload` | 最刺眼：`esm/upload.mjs` **存在**，运行时能 import，类型里却看不见 |
+
+用户遇到这种情况只有两条路：`(window as any)` 或 `@ts-expect-error` —— **两条都绕开了类型系统**，
+而这个库最反对的就是绕过契约。
+
+修法：把 8 个对象的真实形状补进 `FrontendLibGlobal`（形状是逐个读源码确认的，
+不是照抄 README）；只有 `Upload` 加了具名导出 `export declare const Upload`，
+因为只有它在 `esm/` 里有包装模块。声明一个运行时取不到的具名导出，
+正是本库最反对的「幻觉 API」。
+
+### 更正：一句替门禁吹牛的注释
+
+`types/index.d.ts` 里原来写着「behavior-api 门禁核对源码 / esm 入口 / **本文件声明**
+三者集合相等」。核实：`behavior-api-gate.js` 里**一次都没出现** `index.d.ts`，
+它只比源码与 `esm/`。`check-all.sh` 里对同一道门禁的描述也有同样的问题。
+
+⇒ 两处都改成实话，并补上真正做这件事的门禁（下一条）。
+**注释替门禁承诺了它没做的事，比没有门禁更危险** —— 你会以为有人在看。
+
+### 新增门禁：类型与运行时必须对齐
+
+`05-audit/types-globals-gate.py`，三条判据：
+
+1. 源码里每个 `window.X =` / `global.X =`（排除 `==` / `===`）都必须在
+   `FrontendLibGlobal` 里有声明；
+2. 反过来，每条声明都必须能在源码里找到赋值 ⇒ 防「幻觉类型」；
+3. 每个 `export declare const X` 必须有 `esm/<kebab>.mjs` ⇒ 防「幻觉导出」。
+
+反向控制五项：新增一个没声明的全局 / 删掉 `Theme` 的声明 / 声明一个源码里没有的成员 /
+声明一个没有 esm 的具名导出 / 真实仓库必须全绿。
+
+### 修复：`--schema=behaviors` 不可用（E298）
+
+`ai/behaviors.schema.json` 一直都在，`ai/cli.js` 的 `SCHEMAS` 映射里却没有 `behaviors`
+⇒ `node ai/cli.js validate ai/behaviors.json --schema=behaviors` 报「未知 schema」。
+
+后果是这份契约**没有任何工具能校验**：`behaviors.json` 是稳定性承诺里的微行为矩阵，
+写错了只能靠人看。补一行映射即可，已验证能通过也能报错。
+
+---
+
 ## [0.25.3] - 2026-11-03
 
 **修订版：修掉四个「照着文档写会直接失败」的入口问题，并补上三层规范里缺失的那一层。

package/CONTRIBUTING.md

@@ -29,7 +29,7 @@ npm run gate           # 全量：含浏览器类
 npm run gate:fast      # 只跑静态层，不用装浏览器
 ```
 
-全量是 **234 道门禁**（默认 `min(核数, 6)` 路并发，实测 583 秒 / 退出码 0；
+全量是 **235 道门禁**（默认 `min(核数, 6)` 路并发，实测 583 秒 / 退出码 0；
 单道耗时累加 1658 秒，并发效率约 2.8×。组件层要起浏览器，还要逐张比 **109 张**视觉截图 ——
 47 浅色 + 47 暗色 + 15 RTL，按平台分集，只比本平台那套）。
 只想确认没改坏静态契约的话用 `gate:fast`，几秒到几分钟。

package/ai/cli.js

@@ -151,7 +151,11 @@ var SCHEMAS = {
   tokensAudience: 'tokens.audience.schema.json',
   tokensTree: 'tokens.tree.schema.json',
   deprecations: 'deprecations.schema.json',
-  patch: 'patch.schema.json'
+  patch: 'patch.schema.json',
+  /* behaviors 是稳定性承诺里的核心契约（微行为矩阵），
+     它的 schema 文件一直都在，但这里漏登记 ⇒ `--schema=behaviors` 报
+     "未知 schema"，等于这份契约**没有任何工具能校验**（E298）。 */
+  behaviors: 'behaviors.schema.json'
 };
 
 function cmdValidate(args) {

package/ai/components.json

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

package/docs/ACCESSIBILITY.md

@@ -5,7 +5,7 @@
 
 | 项目 | 值 |
 |---|---|
-| 声明适用版本 | agentcss `0.25.3` |
+| 声明适用版本 | agentcss `0.25.4` |
 | 声明日期 | 2026-11-03 |
 | 复核节奏 | 每次发版前重跑（`npm run gate` 内含全部证据） |
 | 范围 | 本库交付的 CSS / JS、全部 `demo.html`（组件页 + 图表页 + 组合页）、以及文档站生成的页面 |

package/index.html

@@ -97,7 +97,7 @@ li a:active { background: var(--surface-sunken); }
   </p>
 </main>
 <footer class="wrap">
-  <p class="note">0.25.3 · 零第三方运行时依赖</p>
+  <p class="note">0.25.4 · 零第三方运行时依赖</p>
 </footer>
 </body>
 </html>

package/llms-full.txt

@@ -1,6 +1,6 @@
 # agentcss — full reference (one file)
 
-> Generated from `ai/components.json` + `ai/pitfalls*.json` + `ai/behaviors.json` at version **0.25.3**.
+> Generated from `ai/components.json` + `ai/pitfalls*.json` + `ai/behaviors.json` at version **0.25.4**.
 > Do not edit by hand: run `python 05-audit/gen-llms.py` (freshness is gated).
 > Short version: `llms.txt`. Machine contract: `ai/*.json`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcss",
-  "version": "0.25.3",
+  "version": "0.25.4",
   "description": "移动 Web 组件库：CSS + 可选行为脚本，零第三方运行时依赖。样式用 bundler 引入，交互行为用 script 标签引入。",
   "keywords": [
     "css",

package/types/index.d.ts

@@ -390,6 +390,114 @@ export interface FlipApi {
   remove(container: HTMLElement, el: HTMLElement, done?: () => void): void;
 }
 
+/* ============================================================================
+ * 资产 / 主题：`01-tokens/`、`09-assets/`、`04-recipes/` 的公开对象
+ *
+ * 🔴 为什么单列一段（0.25.2 的缺陷，0.25.3 补）：这 8 个对象都挂在 window 上，
+ *    但本文件里一个都没有 ⇒ `window.Theme.set('dark')` 在 TS 项目里直接报
+ *    "属性不存在"，用户只能写 `(window as any).Theme` —— 等于绕过类型系统。
+ *    其中 `Upload` 更明显：`esm/upload.mjs` 是**存在**的，运行时能 import，
+ *    类型里却看不见。
+ *
+ *    ⚠️ 本文件从前在这里写过一句「behavior-api 门禁核对源码 / esm 入口 /
+ *    本文件声明三者集合相等」—— 那句话**不成立**：那道门禁只比源码与 esm/，
+ *    从不读本文件（0.25.3 核实过）。现在由 `05-audit/types-globals-gate.py` 判：
+ *    源码里每个 `window.X =` / `global.X =` 都必须在这里有声明，
+ *    反过来每条声明也必须有源码依据。
+ *
+ * 为什么这 7 个不给 `export declare const`：`esm/` 里没有它们的包装模块
+ *    （只有 16 个行为脚本 + upload）。声明一个运行时取不到的具名导出，
+ *    正是本库最反对的「幻觉 API」。它们只能走 `window.X`。
+ * ========================================================================== */
+export type ThemeMode = 'light' | 'dark' | 'auto';
+
+export interface ThemeApi {
+  /** 读当前**模式**（不是"现在是深还是浅"）：auto 也算一种模式 */
+  get(): ThemeMode;
+  /** 当前实际渲染是不是深色（auto 模式下由系统决定） */
+  isDark(): boolean;
+  set(mode: ThemeMode): void;
+  toggle(): void;
+  /** 三态循环：auto → light → dark → auto */
+  cycle(): void;
+}
+
+export interface ChartApi {
+  draw(el: Element): void;
+  /** `draw` 的语义别名：数据变了，重画一次 */
+  emit(el: Element): void;
+  /** 画一个区域里所有 `.sparkline[data-spark]` */
+  update(root?: ParentNode): void;
+  /** ⚠️ 只有浏览器支持 ResizeObserver 时才存在（老 WebView 里是 undefined） */
+  observe?(el?: Element): void;
+}
+
+export interface ChartAdapterPalette {
+  accent: string;
+  danger: string;
+  success: string;
+  warn: string;
+  info: string;
+  [key: string]: string;
+}
+
+export interface ChartAdapterApi {
+  /** 读某个作用域下的 CSS 变量值（`ctx` 决定用哪套主题） */
+  cssVar(name: string, fallback?: string, ctx?: Element): string;
+  palette(ctx?: Element): ChartAdapterPalette;
+  seriesColors(n: number, p: ChartAdapterPalette): string[];
+  /** 生成 ECharts 主题对象；`name` 形如 `fe-light` / `fe-dark` */
+  theme(name: string, p?: ChartAdapterPalette | null, ctx?: Element): object;
+  themeName(ctx?: Element): string;
+  defaults(option?: object, ctx?: Element): object;
+  create(dom: HTMLElement, opt?: object): unknown;
+  /** 主题切换后重设；主题名变了会重建实例（ECharts 的主题在 init 时绑定） */
+  refresh(inst: unknown): unknown;
+}
+
+export interface ModelViewerInstance {
+  build(): void;
+  makeIdle(): void;
+  fail(msg?: string): void;
+  status(text: string): void;
+  load(): void;
+  boot(): void;
+  initScene(): void;
+}
+
+export interface BarApi {
+  draw(opt: {
+    host: HTMLElement;
+    /** 🔴 必填：本库铁律三，量程不得自动适配（漏了会抛错，不会悄悄自适应） */
+    max: number;
+    series?: unknown[];
+    height?: number;
+    mode?: 'group' | 'stack';
+  }): void;
+}
+
+export interface ScientificPlotApi {
+  render(el: Element, spec?: object): void;
+  /** 判据 / 单测用的真值入口；不承诺稳定，改版可能变 */
+  __internals: object;
+}
+
+export interface ShellNavInstance {
+  /** 已开着就直接返回现有句柄（重复点不该叠两层遮罩） */
+  open(): unknown;
+  close(): void;
+  destroy(): void;
+}
+
+export interface UploadInstance {
+  /** 收下一批文件（拖放入口，也是公开 API） */
+  add(incoming: FileList | File[], dirCount?: number): void;
+  render(): void;
+  setState(state: string): void;
+  setProgress(index: number, pct: number): void;
+  removeAt(index: number): void;
+}
+
 /* ============================================================================
  * 全局命名空间（组件脚本是 IIFE，挂到 window）
  * ========================================================================== */
@@ -412,6 +520,18 @@ export interface FrontendLibGlobal {
   Toc: TocApi;
   Reveal: RevealApi;
   FLIP: FlipApi;
+  /* ---- 资产 / 主题（没有 esm 入口，只能走 window.X） ---- */
+  Theme: ThemeApi;
+  Chart: ChartApi;
+  ChartAdapter: ChartAdapterApi;
+  /** construct 形态：`new window.ModelViewer(node)` */
+  ModelViewer: new (node: HTMLElement) => ModelViewerInstance;
+  Bar: BarApi;
+  ScientificPlot: ScientificPlotApi;
+  /** construct 形态：`new window.ShellNav(root, opts)` */
+  ShellNav: new (root: HTMLElement, opts?: object) => ShellNavInstance;
+  /** construct 形态：`new window.Upload(root, opts)` */
+  Upload: new (root: HTMLElement, opts?: object) => UploadInstance;
 }
 
 declare global {
@@ -426,7 +546,8 @@ export declare const Dropdown: FrontendLibGlobal['Dropdown'];
 export declare const Tree: FrontendLibGlobal['Tree'];
 /* 与 `global.X = …` 一一对应（16 个行为脚本全部覆盖）。
    证据：`esm/` 下的 16 个 .mjs 由 `05-audit/gen-esm.py` 从源码生成，
-   `behavior-api` 门禁核对「源码导出 / esm 入口 / 本文件声明」三者集合相等。 */
+   `behavior-api` 门禁核对「源码导出 ↔ esm 入口」两者集合相等
+   （⚠️ 它**不读本文件**；本文件的声明由 `types-globals-gate.py` 判）。 */
 export declare const Accordion: FrontendLibGlobal['Accordion'];
 export declare const Tabs: FrontendLibGlobal['Tabs'];
 export declare const Nav: FrontendLibGlobal['Nav'];
@@ -437,4 +558,7 @@ export declare const Tooltip: TooltipApi;
 export declare const Popover: PopoverApi;
 export declare const Toc: TocApi;
 export declare const Reveal: RevealApi;
-export declare const FLIP: FlipApi;
+export declare const FLIP: FlipApi;
+/* Upload 有 esm 入口（`esm/upload.mjs`）⇒ 可以具名导出；
+   其余 7 个资产/主题对象没有包装模块，只在 FrontendLibGlobal 里声明。 */
+export declare const Upload: FrontendLibGlobal['Upload'];