agentcss 0.25.3 → 0.25.5

package/dist/09-assets/model-viewer/model-viewer.js

@@ -68,8 +68,14 @@ this.btn.addEventListener('click', function () { self.load(); });
 this.ui.appendChild(this.btn);
 
 this.hint = el('p', 'mv__hint');
-this.hint.innerHTML = '模型 <code>' + (this.src.split('/').pop() || '—') +
-'</code> 会<b>点击后才下载</b>，首屏不占流量。';
+
+var fname = el('code', null, this.src.split('/').pop() || '—');
+var strong = el('b', null, '点击后才下载');
+this.hint.appendChild(document.createTextNode('模型 '));
+this.hint.appendChild(fname);
+this.hint.appendChild(document.createTextNode(' 会'));
+this.hint.appendChild(strong);
+this.hint.appendChild(document.createTextNode('，首屏不占流量。'));
 this.ui.appendChild(this.hint);
 
 if (!hasWebGL()) {
@@ -260,6 +266,7 @@ self.raf = requestAnimationFrame(loop);
 self.ui.innerHTML = '';
 var cap = el('p', 'mv__cap');
 var dt = Math.round(((window.performance && performance.now) ? performance.now() : Date.now()) - t0);
+
 cap.innerHTML = '模型 <b>' + fmtKB(bytes || self.lastBytes || 0) + '</b> · 引擎就绪耗时 <b>' + dt + 'ms</b>' +
 (controls ? ' · 拖动可旋转，滚轮/双指可缩放' : ' · 未加载控制器，无法拖动');
 self.node.appendChild(cap);

package/dist/09-assets/scientific-plot/scientific-plot.js

@@ -501,6 +501,7 @@ return String(s == null ? '' : s)
       legendHtml = '<ul class="splot__legend">' + items.join('') + '</ul>';
     }
 
+    /* @html-sink internal — svg 由本文件生成，图例名字已过 esc() */
     el.innerHTML = svg + legendHtml;
     return {
       svg: el.firstChild,

package/dist/COSTS.md

@@ -22,12 +22,12 @@
 | primitive | `button` | 2.9 KB | 1.0 KB | — | **3.9 KB** | 28.3 KB | −24.4 KB |
 | primitive | `card` | 2.9 KB | 0.9 KB | — | **3.9 KB** | 26.0 KB | −22.1 KB |
 | primitive | `choice` | 2.9 KB | 1.1 KB | — | **4.1 KB** | 28.1 KB | −24.0 KB |
-| primitive | `combobox` | 2.9 KB | 1.0 KB | 5.4 KB | **9.3 KB** | 31.4 KB | −22.2 KB |
-| primitive | `date-range` | 2.9 KB | 0.8 KB | 2.5 KB | **6.3 KB** | 28.4 KB | −22.1 KB |
+| primitive | `combobox` | 2.9 KB | 1.0 KB | 5.5 KB | **9.4 KB** | 31.5 KB | −22.1 KB |
+| primitive | `date-range` | 2.9 KB | 0.8 KB | 2.6 KB | **6.3 KB** | 28.6 KB | −22.3 KB |
 | primitive | `delta` | 2.9 KB | 0.3 KB | — | **3.2 KB** | 24.7 KB | −21.5 KB |
 | primitive | `input` | 2.9 KB | 1.0 KB | — | **4.0 KB** | 25.8 KB | −21.9 KB |
 | primitive | `metric` | 2.9 KB | 0.5 KB | — | **3.4 KB** | 25.1 KB | −21.7 KB |
-| primitive | `popover` | 2.9 KB | 0.8 KB | 2.2 KB | **5.9 KB** | 29.2 KB | −23.3 KB |
+| primitive | `popover` | 2.9 KB | 0.8 KB | 2.2 KB | **5.9 KB** | 29.3 KB | −23.4 KB |
 | primitive | `progress` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 26.2 KB | −22.5 KB |
 | primitive | `select` | 2.9 KB | 0.8 KB | 4.1 KB | **7.9 KB** | 32.9 KB | −24.9 KB |
 | primitive | `separator` | 2.9 KB | 0.2 KB | — | **3.2 KB** | 23.2 KB | −20.0 KB |
@@ -37,7 +37,7 @@
 | primitive | `upload` | 2.9 KB | 1.4 KB | 4.2 KB | **8.5 KB** | 39.3 KB | −30.8 KB |
 | pattern | `accordion` | 2.9 KB | 1.3 KB | 1.8 KB | **6.0 KB** | 36.4 KB | −30.4 KB |
 | pattern | `content` | 2.9 KB | 1.0 KB | — | **4.0 KB** | 26.5 KB | −22.5 KB |
-| pattern | `drawer` | 2.9 KB | 0.8 KB | 2.6 KB | **6.3 KB** | 30.1 KB | −23.8 KB |
+| pattern | `drawer` | 2.9 KB | 0.8 KB | 2.6 KB | **6.3 KB** | 30.2 KB | −23.9 KB |
 | pattern | `dropdown` | 2.9 KB | 0.8 KB | 3.5 KB | **7.2 KB** | 31.6 KB | −24.4 KB |
 | pattern | `form-validation` | 2.9 KB | 0.8 KB | — | **3.7 KB** | 26.8 KB | −23.1 KB |
 | pattern | `list` | 2.9 KB | 0.6 KB | — | **3.5 KB** | 24.3 KB | −20.8 KB |
@@ -52,8 +52,8 @@
 
 ## 三、全库
 
-- 全部组件都用上（min，含 tokens 一份）：**70.4 KB**
-- 源码版（带注释）全库 gzip：358.8 KB
+- 全部组件都用上（min，含 tokens 一份）：**70.6 KB**
+- 源码版（带注释）全库 gzip：380.1 KB
 
 > ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 69% 是注释，字节口径）。
 > 它的用途只有一个 —— 让人看清"dist 到底省了多少"。

package/docs/ACCESSIBILITY.md

@@ -5,8 +5,8 @@
 
 | 项目 | 值 |
 |---|---|
-| 声明适用版本 | agentcss `0.25.3` |
-| 声明日期 | 2026-11-03 |
+| 声明适用版本 | agentcss `0.25.5` |
+| 声明日期 | 2026-11-04 |
 | 复核节奏 | 每次发版前重跑（`npm run gate` 内含全部证据） |
 | 范围 | 本库交付的 CSS / JS、全部 `demo.html`（组件页 + 图表页 + 组合页）、以及文档站生成的页面 |
 | 不在范围 | 使用者拿这些组件拼出来的业务页面（那是你的无障碍责任，不是库的） |

package/docs/CONVENTIONS.md

@@ -139,14 +139,26 @@
 所以"未分层"是当前唯一安全的选择。`cascade-layer-gate.py` 把这条变成可判状态：
 一旦出现第一条 `@layer`，就要求三条前提的实测记录已落档，否则红。
 
-`!important` 现有 10 处，**每一处都必须能被归类**：
+`!important` **每一处都必须能被归类**，归不了类的 ⇒ 红。判据不是"清零" ——
+清零会逼人删掉无障碍兜底。
 
-| 类别 | 处数 | 为什么必须赢 |
-|---|---|---|
-| 无障碍偏好（`prefers-reduced-motion`） | 9 | 操作系统级偏好，组件无权推翻 |
-| 正确性（`[hidden] { display: none }`） | 1 | 不赢就会"藏不住" |
+| 类别 | 为什么必须赢 |
+|---|---|
+| 无障碍偏好（`prefers-reduced-motion: reduce`） | 操作系统级偏好，组件无权推翻 |
+| 正确性（`[hidden] { display: none }`） | 不赢就会"藏不住" |
+| 打印媒体（`@media print` + `display: none`） | 纸张上没有交互，屏幕专属元素必须真的不出现 |
+
+**这里刻意不写"现在有几处"**（I-7：同一个数字有第二个出处，就必然漂移）。
+要数字就跑门禁，它会把每一类的处数打出来：
+
+```bash
+python 05-audit/cascade-layer-gate.py
+```
 
-分不了类的 `!important` ⇒ 红。判据不是"清零"——清零会逼人删掉无障碍兜底。
+> 曾经的教训：这份文档写"10 处（无障碍 9 + `[hidden]` 1）"，而门禁当时实测
+> **13 处**——多出来的 2 处是打印媒体，文档连这个类别都没列。
+> 于是按文档去审计的人会把 2 处**判成"说不清"**，而那两处恰恰是正当的。
+> 少写一个类别，比少写一个数字更坏。
 
 ## 八 · 对比度与触控的硬线
 

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.5 · 零第三方运行时依赖</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.5**.
 > 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.5",
   "description": "移动 Web 组件库：CSS + 可选行为脚本，零第三方运行时依赖。样式用 bundler 引入，交互行为用 script 标签引入。",
   "keywords": [
     "css",
@@ -23,6 +23,8 @@
       "default": "./esm/index.mjs"
     },
     "./tokens.css": "./dist/01-tokens/tokens.css",
+    "./tokens.core.css": "./dist/01-tokens/tokens.core.css",
+    "./base.reset.css": "./dist/01-tokens/base.reset.css",
     "./typography.css": "./dist/01-tokens/typography.css",
     "./page.css": "./dist/01-tokens/page.css",
     "./esm": {

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'];