agentcss 0.24.2 → 0.25.0

package/03-patterns/overlay/overlay.js

@@ -116,17 +116,19 @@
     for (var i = 0; i < inertRefs.length; i++) {
       if (inertRefs[i].node === node) { inertRefs[i].count++; return; }
     }
-    inertRefs.push({ node: node, count: 1 });
+    /* 🔴 记下**打开之前**的状态：页面可能本来就把某块设为 inert
+       （比如另一个弹层、或宿主自己的锁屏）。固定写回 false 会把它误解锁。 */
+    inertRefs.push({ node: node, count: 1, prev: node.inert === true });
     node.inert = true;
   }
 
-  /** 还一个引用；降到 0 才真正解锁。 */
+  /** 还一个引用；降到 0 才真正还原。 */
   function inertRelease(node) {
     for (var i = 0; i < inertRefs.length; i++) {
       if (inertRefs[i].node !== node) continue;
       inertRefs[i].count--;
       if (inertRefs[i].count <= 0) {
-        node.inert = false;
+        node.inert = inertRefs[i].prev === true;
         inertRefs.splice(i, 1);
       }
       return;
@@ -578,17 +580,58 @@
     var nodes = Array.prototype.slice.call(
       document.body.querySelectorAll('body > *')
     );
-    nodes.forEach(function (n) {
-      /* 任何已有的 backdrop（外层）都跳过 —— 它们自己管自己的 */
-      if (n.classList.contains('dialog-backdrop')) return;
-      if (useInert) {
-        inerted.push(n);
-        inertAcquire(n);
-      } else {
-        ariaed.push(n);
-        ariaAcquire(n);
-      }
-    });
+    /* 🔴 以前这里 `if (n.classList.contains('dialog-backdrop')) return;`
+       —— 把所有已存在的弹层（外层 dialog）当成"它自己管自己"跳过了。
+       实际后果：开 A 再开 B，A 既没 inert 也没 aria-hidden，
+       **两个 dialog 同时暴露给读屏**，Tab 也能从 B 走回 A（有 inert 时
+       虽然背景被锁，但 A 和 B 都是"前景"，只是在同一个 body 下并列）。
+       ⇒ 正解：只跳过**自己**这一层 backdrop，别的弹层照常隔离。 */
+    function isolate(n) {
+      if (!n || n === backdrop) return;
+      if (useInert) { inerted.push(n); inertAcquire(n); }
+      else { ariaed.push(n); ariaAcquire(n); }
+    }
+    nodes.forEach(isolate);
+
+    /* 🔴 只在 open 时拍一次快照是不够的：弹层开着的时候，
+       宿主页面完全可能再往 body 里插东西（toast、埋点 iframe、框架的 portal）。
+       那些节点不在快照里 ⇒ 不受隔离 ⇒ 读屏和 Tab 都能进。
+       ⇒ 用 MutationObserver 补：**只盯 body 的直接子节点**（与快照口径一致），
+          且不隔离新出现的 backdrop —— 那是"又开了一层"，它会自己隔离别人。 */
+    var mo = null;
+    if (typeof window.MutationObserver === 'function') {
+      mo = new window.MutationObserver(function (records) {
+        /* 🔴 自愈：如果这一层的 backdrop 已经被**外部**从 DOM 里摘掉
+           （框架卸载、测试清理、别人 innerHTML='' 都会这么干），
+           那 close() 永远不会跑 ⇒ 观察器成了幽灵：
+           它会继续把之后插入 body 的节点一个个设成 inert，且没人释放。
+           症状：后续任何 dialog 都抢不回焦点（目标节点被幽灵锁着）。
+           ⇒ 一旦发现自己已不在文档里，就地回收。 */
+        if (!document.documentElement.contains(backdrop)) {
+          if (mo) { mo.disconnect(); mo = null; }
+          if (closed) return;              /* 正常 close 已还过，别还第二次 */
+          closed = true;
+          inerted.forEach(inertRelease);
+          ariaed.forEach(ariaRelease);
+          inerted = [];
+          ariaed = [];
+          if (uninstallIsolation) { uninstallIsolation(); uninstallIsolation = null; }
+          unlockScroll();
+          return;
+        }
+        for (var r = 0; r < records.length; r++) {
+          var added = records[r].addedNodes;
+          for (var a = 0; a < added.length; a++) {
+            var n = added[a];
+            if (!n || n.nodeType !== 1) continue;
+            if (n.classList && n.classList.contains('dialog-backdrop')) continue;
+            if (n.inert === true || n.getAttribute('aria-hidden') === 'true') continue;
+            isolate(n);
+          }
+        }
+      });
+      mo.observe(document.body, { childList: true });
+    }
 
     function close() {
       if (closed) return;
@@ -616,6 +659,7 @@
         if (openStack[si] === stackEntry) { openStack.splice(si, 1); break; }
       }
       if (uninstallIsolation) { uninstallIsolation(); uninstallIsolation = null; }
+      if (mo) { mo.disconnect(); mo = null; }
 
       /* ⭐ 引用计数：还一个引用，降到 0 才真的解锁 ⇒ 与关闭顺序无关 */
       inerted.forEach(inertRelease);
@@ -623,9 +667,11 @@
       ariaed.forEach(ariaRelease);
       unlockScroll();
 
-      /* 🔴 焦点必须回到**触发它的那个元素**。
-         不还的话，键盘用户要重新 Tab 一遍才能回到原处。 */
-      fr.restore();
+      /* 🔴 焦点必须回到**触发它的那个元素**，但**只在焦点还是我的时候**。
+         `focusIsMine` 这个判断以前算了却没用（死变量）⇒ 关外层时会把
+         焦点从内层手里抢走。现在真的拿它把关。 */
+      if (focusIsMine) fr.restore();
+      else fr.clear();
       /* ⚠️ 不写 `document.body.focus()`：body 默认不可聚焦，
          那行从来没起过作用，只会让人以为"有兜底"。 */
     }

package/03-patterns/states/README.md

@@ -36,6 +36,21 @@
 
 骨架屏必须标 `aria-hidden="true"`，否则屏幕阅读器会把它读成一堆无意义色块。
 
+### 形状变体（本文件自带一份，注意与 primitive 重复）
+
+| 类 | 形状 |
+|---|---|
+| `.skeleton` | 底块（底色 `--surface-sunken`，圆角 `--r-sm`，带微光扫过） |
+| `.skeleton--text` | 一行文字（`height:1em`，下边距 `0.35em`）；`:last-child` 收窄到 70%，看起来像段落结尾 |
+| `.skeleton--title` | 标题行（`height:1.4em`，宽度 60%） |
+| `.skeleton--avatar` | 头像（`40×40`，`--r-pill` 全圆），配 `.skeleton--text` 做列表项占位 |
+| `.skeleton--block` | 大块内容区（`height:120px`） |
+
+> ⚠️ **`02-primitives/skeleton/skeleton.css` 里另有一份实现**，两者已分叉
+> （底色令牌、高度写法、变体集合都不同：那边有 `--circle` 没有 `--avatar`/`--title`）。
+> 谁后加载谁生效。已登记在 `05-audit/css-ownership.json`，去重计划在 0.26.0。
+> **本文件只用 `.skeleton` 时，请引 primitive 那份，别两边都引。**
+
 ---
 
 ## 300ms 延迟（需要 JS，约 10 行）

package/03-patterns/states/states.css

@@ -129,7 +129,24 @@
   background: linear-gradient(90deg,
               transparent 0%, var(--sk-hi) 50%, transparent 100%);
   transform: translateX(-100%);
-  animation: skeleton-sweep 1.4s ease-in-out infinite;
+}
+/* 🔴 动画必须包在 `prefers-reduced-motion: no-preference` 里（WCAG 2.3.3）。
+   以前这里是**无条件** `animation: skeleton-sweep 1.4s infinite`：
+
+     · 本文件先加载（states/demo.html 就是这种情况，它没引 skeleton.css）
+       ⇒ 减少动态效果的用户照样看到闪烁的微光；
+     · 与 `02-primitives/skeleton/skeleton.css` 同特异性 ⇒ 谁后加载谁定生死。
+
+   即"要不要尊重减少动态效果"取决于 CSS 顺序。与 E254 同类。
+   ⚠️ 这里与 skeleton.css 是**两份实现**（已登记在 css-ownership.json），
+      修的时候两边都要看。 */
+@media (prefers-reduced-motion: no-preference) {
+  .skeleton::after {
+    animation: skeleton-sweep 1.4s ease-in-out infinite;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .skeleton::after { animation: none; opacity: 0; }
 }
 @keyframes skeleton-sweep {
   to { transform: translateX(100%); }

package/03-patterns/tooltip/README.md

@@ -31,6 +31,18 @@ Tooltip.attach(按钮, '说明文字', 'top');
 | `text` | string | 纯文本（用 `textContent` 写入，**天然免疫注入**）|
 | `place` | `top`（默认）/ `bottom` / `inset-inline-start` / `inset-inline-end` | 方位 |
 
+`place` 原样拼进类名（`.tooltip--` + `place`），所以四个方位对应的就是这四个类：
+
+| 类 | 出现位置 |
+|---|---|
+| `.tooltip--top` | 在触发元素**下方**，箭头朝上（默认） |
+| `.tooltip--bottom` | 在触发元素**上方**，箭头朝下 |
+| `.tooltip--inset-inline-start` | 在触发元素**右侧**，箭头朝左。用逻辑属性，RTL 下自动镜像到左边 |
+| `.tooltip--inset-inline-end` | 在触发元素**左侧**，箭头朝右。同样随书写方向镜像 |
+
+⚠️ 方位名容易读反：`--top` 指的是**箭头朝上**，所以气泡在下方。
+换成"气泡在哪边"去想会写错。
+
 公开 API 只有 `Tooltip.attach()`，**没有** `show` / `hide` ——
 显隐由 hover / focus / click 自动驱动。
 

package/04-recipes/longform/longform.html

@@ -106,7 +106,7 @@ body {
 
 /* ---------------------------------------------------------------- 布局
    ⚠️ 改版：原来容器 1040px + 目录 13rem + 正文 68ch = 896px，
-   右边空出 144px，视觉重心整个偏左 —— 评审意见"排版混乱"。
+   右边空出 144px，视觉重心整个偏左 —— 整页看起来是散的。
 
    改法不是"匀称"，是**把空间用完**：
      容器 920px = 目录 11rem(176) + gap 40 + 正文 72ch(≈680) + 余量 24
@@ -152,7 +152,7 @@ body {
 
 /* 这一页唯一的视觉焦点。
    🔴 改版要点：标题从衬线改成**无衬线 + 更大 + 紧字距**。
-      原来衬线 40px 只比正文大一档，撑不起焦点（评审意见"视觉效果不强"）。
+      原来衬线 40px 只比正文大一档，撑不起焦点。
       现在无衬线 + 最大 3.4rem + letter-spacing -0.02em ≈ 正文的 2.5 倍，
       而正文保留衬线保证长文可读 —— **两者优势都占**。 */
 .article__title {
@@ -187,7 +187,7 @@ body {
 }
 
 /* 小标题：无衬线，与主标题同一套语言 —— 层级靠字号和字重，不靠颜色
-   🔴 改版第二轮：评审意见"整体尖锐、仍有 AI 痕迹"。
+   🔴 改版第二轮：整体偏尖锐，仍有"模板感"。
       诊断来源：① 通栏 1px 灰线（硬边）② 字距 -0.022em + weight 600（太紧太重）
       处理：通栏线换成**短蓝线段**（经典编辑排版手法，软化且增加节奏），
             字距放宽、字重降一级。锐度降下来，但层级对比反而更清楚。 */

package/04-recipes/report/README.md

@@ -54,6 +54,15 @@ report.css                   ← 本系统
 > ⭐ 为什么钉死六种：报告里每多一种"自创角色"，读者的解读负担就多一分。
 > 发现自己在写第七种时，应该回头用**结构**（列表、表格、引用）而不是字号表达。
 
+导语有两个名字，**`.rep__standfirst` 与 `.rep__lede` 是同一条规则**（分组选择器）：
+
+| 类 | 说明 |
+|---|---|
+| `.rep__standfirst` | 推荐用这个（全库其余地方都这么叫） |
+| `.rep__lede` | 兼容别名，早期版本用过。留着是为了不让老页面掉样式，新代码别用 |
+
+两者都吃 `--rep-lead-fs` / `--lh-loose` / `--measure-lede`，改一个变量两边一起变。
+
 ### 标记骨架
 
 ```html

package/04-recipes/report/report.css

@@ -361,4 +361,9 @@
   .rep__fig,
   .rep table { break-inside: avoid; }
   .rep__pull { border-inline-start-width: 2px; }
+  /* 孤行寡行：段首/段尾不要只留一行在另一页。
+     ⚠️ 必须带 `.rep` 前缀 —— 裸 `p` / `li` 会改掉宿主页面所有段落，
+        那是 `bleed-gate` 的硬红线（组件只影响自己）。
+     其他配方 / 使用者的页面要这一条，自己写同样的三行即可。 */
+  .rep p, .rep li, .rep blockquote { orphans: 2; widows: 2; }
 }

package/04-recipes/table/README.md

@@ -19,6 +19,22 @@
 | （默认 / `.table--financial`） | 业务与财务数据 | 粘性表头、数字右对齐 + 等宽数字、行高亮 |
 | `.table--academic` | 学术出版 | **三线表**：去掉竖线/斑马纹/行分隔线，只留顶线、表头下线、底线 |
 | `.table--stats` | 统计与实验结果 | 估计值 / 标准误 / 置信区间 / p 值各有位置与样式 |
+| `.table--compact` | 密度高、一屏要塞很多行 | 字号降到 `--fs-xs`，单元格内边距收到 `--sp-1 --sp-2`。**只用在小字不伤可读性的场合**（数字表、对账表），正文表格别用 |
+
+### 缺失值：`.cell--na`
+
+空单元格放一个"没有值"的标记时用它（`--text-tertiary` + 居中）：
+
+```html
+<td class="cell--na">—</td>
+<td class="cell--na">N/A</td>
+```
+
+为什么要有专门的类：**空着和"没有"不是一回事**。空单元格读者不知道是漏了还是本来就没有；
+直接写个普通文本的"—"又会继承数字列的右对齐和等宽字体，看起来像一个数据。
+`.cell--na` 把它拉回中性表达。
+
+> 只写 `.table .cell--na` 生效（必须在这张表里面）。
 
 ## 列定义（示例页里的用法）
 

package/04-recipes/tierA-tokens.css

@@ -145,7 +145,7 @@
 
 }
 
-@media (prefers-color-scheme: dark) {
+@media screen and (prefers-color-scheme: dark) {
 
 :root:not([data-theme="light"]) {
   --paper:           #14171A;
@@ -163,8 +163,8 @@
   --text-primary:    #E4E7EA;
   --text-secondary:  #AEB6C0;
   --text-tertiary:   #9BA3AD;
-  --text-on-accent:  #0D1114;
-  --text-on-solid:   #0D1114;
+  --text-on-accent:  #15181c;
+  --text-on-solid:   #15181c;
   --skeleton-bg:       #2E343C;
   --skeleton-shimmer:   rgba(255, 255, 255, 0.06);
 

package/09-assets/README.md

@@ -25,6 +25,24 @@ python -m http.server 8000
 # 然后打开 http://127.0.0.1:8000/09-assets/sparkline/demo.html
 ```
 
+## 从 JS 画东西时：主题色要按**作用域**读
+
+本库的主题是容器级的 —— `[data-theme="dark"]` 可以只罩住一块区域。
+所以 JS 资产**不能**只读 `document.documentElement`：
+
+```js
+// ❌ 暗容器里的图表会拿到浅色令牌（实测 1.01:1，字看不见）
+getComputedStyle(document.documentElement).getPropertyValue('--text-primary')
+
+// ✅ 由渲染目标往上找作用域
+getComputedStyle(el.closest('[data-theme]') || document.documentElement)
+  .getPropertyValue('--text-primary')
+```
+
+判"当前是明还是暗"要量 `--paper` 的**亮度**，不要读 `data-theme` 属性、也不要拿令牌值和字面量比
+（`theme-toggle.js` 只把 `data-theme-current` 写在 `:root` 上，容器永远读不到）。
+`theme-scope-gate` 的 ⑥ 会检查这一点：新加的 JS 资产若从根读颜色，门禁直接红。
+
 ## 图标：本库不内置，需要就自己内联
 
 要"关闭""警告""箭头"这类图形时，**一律内联 SVG** ——

package/09-assets/bar/bar.css

@@ -130,6 +130,15 @@
 .bar__label--max   { fill: var(--text-primary); font-weight: 700; }
 .bar__label--clip  { fill: var(--danger, #c0392b); font-weight: 700; }
 
+/* 打印：描边去掉。
+   那圈 `var(--surface)` 光晕在屏幕上是为了把标注从深色柱子上"抠"出来；
+   纸上没有深色柱子（底色被丢弃），光晕反而变成一圈**白色文字轮廓**。
+   实测（0.24.2，`examples/finance-report`）：`stroke: none` 之后，
+   产物里 4 段 #FFFFFF 的文字 run 消失，最差对比度从 1.00:1 升到 5.72:1。 */
+@media print {
+  .bar__label { stroke: none; }
+}
+
 /* ---------- 越界说明 ---------- */
 .bar__note {
   margin: var(--sp-2) 0 0;
@@ -154,13 +163,19 @@
   }
 }
 
-/* ---------- 暗色下容器要跟着换 ---------- */
-@media (prefers-color-scheme: dark) {
-  .bar {
-    background: var(--surface, #1a1c1e);
-    border-color: var(--border-decor);
-  }
-  .bar__label {
-    stroke: var(--surface, #1a1c1e);
-  }
-}
+/* ---------- 暗色：**不在这里写分支** ----------
+   这里原来有一段针对 `prefers-color-scheme: dark` 的媒体查询块，
+   里面只有两条：`.bar` 的 background 与 `.bar__label` 的 stroke。
+   ⚠️ 那段文字在这里**故意不照抄**：多个门禁拿这个字符串当锚点，
+      注释里出现字面量会把它们带偏（E199 踩过一次）。
+   它做的只有一件事：把 `var()` 的**兜底值**从 #fff 换成暗色值。
+   令牌在的时候（本库的正式用法）两条声明解析结果完全相同 ⇒ 纯冗余。
+
+   代价却是真的：
+     · 它让这个资产自己长出一个主题分支，绕过令牌层
+       （`theme-scope-gate` 判据⑤ 只扫 02/03/04，扫不到 09-assets，
+        所以这条分支一直绿着存在）；
+     · 打印时它照样命中 ⇒ SVG 描边在纸上用暗色值，而底色已被丢弃。
+
+   ⇒ 主题一律由令牌承担。没有令牌时用的是浅色兜底（#fff），
+     这正是"没装令牌就别指望暗色"的应有行为。 */

package/09-assets/echarts-adapter/demo.html

@@ -182,7 +182,9 @@ var c = ChartAdapter.create(document.getElementById('chart'), {
 // ↑ 就这样。主题、y 轴从 0、字号、网格边距都已经合规了。</code></pre>
   </div>
   <p class="note">
-    换主题时调 <code>ChartAdapter.refresh(c)</code>，图表会跟着变
+    换主题时调 <code>c = ChartAdapter.refresh(c)</code>，图表会跟着变 ——
+    <strong>它会返回一个新实例</strong>（ECharts 的主题在 init 时绑定，换主题必须重建），
+    不接返回值就会拿到一个已 dispose 的旧实例
     （配合 <code>01-tokens/theme-toggle.js</code>）。
   </p>
 </div>

package/09-assets/echarts-adapter/echarts-adapter.js

@@ -45,32 +45,53 @@
 
   /* ---------- 1. 从 CSS 变量取令牌 ---------- */
 
-  /** 读一个 CSS 变量（读不到就返回 fallback）。 */
-  function cssVar(name, fallback) {
+  /**
+   * 读一个 CSS 变量（读不到就返回 fallback）。
+   * @param {string} name
+   * @param {string} fallback
+   * @param {Element} [ctx]  作用域元素；默认根元素
+   *
+   * 🔴 为什么必须有 ctx
+   *   本库的主题是**容器级**的：`[data-theme="dark"]` 可以只罩住一块区域
+   *   （tokens.css 里 `[data-theme="dark"]` 与 `:root[data-theme="dark"]` 并列）。
+   *   只读 `document.documentElement` 的话，暗容器里的图表会拿到**浅色**令牌：
+   *   实测 `--text-primary` = #15181c，而该容器 `--paper` = #14171A ⇒ **1.01:1**。
+   *   文字不是「不够清楚」，是根本看不见。
+   */
+  function cssVar(name, fallback, ctx) {
     if (typeof window.getComputedStyle !== 'function') return fallback;
-    var v = getComputedStyle(document.documentElement).getPropertyValue(name);
+    var el = ctx || document.documentElement;
+    var v = getComputedStyle(el).getPropertyValue(name);
     return (v && v.trim()) || fallback;
   }
 
+  /** 图表该跟随谁的主题：最近的一个 `[data-theme]` 祖先，没有就是根。 */
+  function scopeOf(el) {
+    try {
+      if (el && el.closest) return el.closest('[data-theme]') || document.documentElement;
+    } catch (e) { /* 老浏览器 / 脱离文档的节点 */ }
+    return document.documentElement;
+  }
+
   /**
    * 拿到本库的调色板。
    * 🔴 全部有 fallback —— 万一页面没引 tokens.css 也能出图
    *    （不因为缺令牌就整个图表画不出来）。
    */
-  function palette() {
+  function palette(ctx) {
     return {
-      text: cssVar('--text-primary', '#15181c'),
-      textSub: cssVar('--text-secondary', '#5b6472'),
-      textTertiary: cssVar('--text-tertiary', '#8a94a3'),
-      surface: cssVar('--surface', '#ffffff'),
-      paper: cssVar('--paper', '#f6f7f8'),
-      border: cssVar('--border-decor', '#e2e5e9'),
-      borderStrong: cssVar('--border-control', '#868b94'),
-      danger: cssVar('--danger', '#c0392b'),   // A 股：涨红
-      success: cssVar('--success', '#2e7d52'), // 跌绿
-      warn: cssVar('--warning', '#b8860b'),
-      info: cssVar('--info', '#2b7a9e'),
-      accent: cssVar('--accent', '#1b4d8f'),
+      text: cssVar('--text-primary', '#15181c', ctx),
+      textSub: cssVar('--text-secondary', '#5b6472', ctx),
+      textTertiary: cssVar('--text-tertiary', '#8a94a3', ctx),
+      surface: cssVar('--surface', '#ffffff', ctx),
+      paper: cssVar('--paper', '#f6f7f8', ctx),
+      border: cssVar('--border-decor', '#e2e5e9', ctx),
+      borderStrong: cssVar('--border-control', '#868b94', ctx),
+      danger: cssVar('--danger', '#c0392b', ctx),   // A 股：涨红
+      success: cssVar('--success', '#2e7d52', ctx), // 跌绿
+      warn: cssVar('--warning', '#b8860b', ctx),
+      info: cssVar('--info', '#2b7a9e', ctx),
+      accent: cssVar('--accent', '#1b4d8f', ctx),
     };
   }
 
@@ -92,22 +113,62 @@
 
   /* ---------- 3. 主题对象（喂给 echarts.registerTheme） ---------- */
 
+  /** 把一个 CSS 颜色解析成 [r,g,b]（认 #rgb / #rrggbb / rgb() / rgba()）。 */
+  function parseColor(v) {
+    if (!v) return null;
+    var t = String(v).trim();
+    var m = /^#([0-9a-f]{3})$/i.exec(t);
+    if (m) {
+      return [parseInt(m[1][0] + m[1][0], 16),
+              parseInt(m[1][1] + m[1][1], 16),
+              parseInt(m[1][2] + m[1][2], 16)];
+    }
+    m = /^#([0-9a-f]{6})$/i.exec(t);
+    if (m) {
+      return [parseInt(m[1].slice(0, 2), 16),
+              parseInt(m[1].slice(2, 4), 16),
+              parseInt(m[1].slice(4, 6), 16)];
+    }
+    m = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/i.exec(t);
+    if (m) return [Math.round(+m[1]), Math.round(+m[2]), Math.round(+m[3])];
+    return null;
+  }
+
+  /**
+   * 这个作用域是不是暗色 —— 读它**实际解析出来**的 `--paper` 算相对亮度。
+   *
+   * 🔴 为什么不用 `data-theme` / `data-theme-current` 属性
+   *   · `data-theme-current` 只由 theme-toggle.js 写在 `:root` 上；
+   *     容器级暗色永远不会设置它 ⇒ 属性判定在容器里恒为「浅色」。
+   *   · 就算改用 `data-theme`，也只回答了「声明了什么」，没回答「算出什么色」。
+   *   令牌系统允许项目覆盖 `--paper`，只有量出来的亮度才是事实（同 I-10）。
+   */
+  function isDarkScope(ctx) {
+    var c = parseColor(cssVar('--paper', '', ctx));
+    if (!c) return false;
+    var lin = c.map(function (v) {
+      v = v / 255;
+      return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+    });
+    // 相对亮度 < 0.18 判暗（#14171A ≈ 0.008，#f6f7f8 ≈ 0.90，中间没有歧义）
+    return (0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2]) < 0.18;
+  }
+
   /**
    * 生成 ECharts 主题。
    * @param {string} name  主题名
    * @param {object} p     调色板（默认自动取）
    */
-  function theme(name, p) {
-    p = p || palette();
-    var isDark = document.documentElement.getAttribute('data-theme-current') === 'dark'
-              || cssVar('--paper', '#fff') !== '#f6f7f8';
+  function theme(name, p, ctx) {
+    p = p || palette(ctx);
+    var isDark = isDarkScope(ctx);
 
     return {
       color: [p.accent, p.danger, p.success, p.warn, p.info],
       backgroundColor: 'transparent',   // 交给页面的背景
       textStyle: {
         color: p.text,
-        fontFamily: cssVar('--sans', 'system-ui, sans-serif'),
+        fontFamily: cssVar('--sans', 'system-ui, sans-serif', ctx),
       },
       title: {
         textStyle: { color: p.text, fontWeight: 600 },
@@ -115,7 +176,9 @@
       },
       legend: { textStyle: { color: p.textSub } },
       tooltip: {
-        backgroundColor: isDark ? '#1c2024' : '#ffffff',
+        // 令牌即真值：暗档 --surface 实测 = #1C2024（与原来写死的值同色），
+        // 亮档 = #ffffff ⇒ 换成令牌后**像素零变化**，但能跟随容器作用域。
+        backgroundColor: cssVar('--surface', isDark ? '#1c2024' : '#ffffff', ctx),
         borderColor: p.border,
         borderWidth: 1,
         textStyle: { color: p.text, fontSize: 12 },
@@ -148,13 +211,13 @@
    * 一组**符合图表规范**的默认 option。
    * 覆盖 ECharts 的默认值 —— 让你不写就合规。
    */
-  function defaults(option) {
-    var p = palette();
+  function defaults(option, ctx) {
+    var p = palette(ctx);
     var o = option || {};
 
     // 🔴 数字格式：千分位 + 等宽
     o.textStyle = merge(o.textStyle, {
-      fontFamily: cssVar('--mono', 'ui-monospace, monospace'),
+      fontFamily: cssVar('--mono', 'ui-monospace, monospace', ctx),
     });
 
     // 网格：留够左边距给 y 轴标签
@@ -214,9 +277,14 @@
    *      ② setOption(option, themeName)
    *    不需要任何"先注册再重初始化"的 dance。
    */
-  function currentThemeName() {
-    return 'fe-' +
-      (document.documentElement.getAttribute('data-theme-current') || 'light');
+  /**
+   * 主题名 = 调色板身份，必须**按作用域**取。
+   * 🔴 `registerTheme` 是全局按名字登记的：一个暗容器里的图和一个页外亮色的图
+   *    如果都叫 `fe-light`，后登记的那个会把前一个的配色顶掉 —— 同页两个图表
+   *    互相污染，而且看起来「某一块莫名其妙变亮了」。
+   */
+  function currentThemeName(ctx) {
+    return 'fe-' + (isDarkScope(ctx) ? 'dark' : 'light');
   }
 
   function create(dom, opt) {
@@ -227,16 +295,17 @@
       }
       return null;
     }
-    var name = currentThemeName();
+    var ctx = scopeOf(dom);
+    var name = currentThemeName(ctx);
     // 🔴 每次都注册：换主题后令牌变了，得重新注册同名主题
     if (typeof window.echarts.registerTheme === 'function') {
-      window.echarts.registerTheme(name, theme(name));
+      window.echarts.registerTheme(name, theme(name, null, ctx));
     }
     var inst = window.echarts.init(dom, name);
     inst.__feDom = dom;          // refresh 要用
     inst.__feOpts = opt || {};
     inst.__feTheme = name;
-    inst.setOption(defaults(inst.__feOpts));
+    inst.setOption(defaults(inst.__feOpts, ctx));
     return inst;
   }
 
@@ -254,14 +323,18 @@
     palette: palette,
     seriesColors: seriesColors,
     theme: theme,
+    /** 作用域对应的主题名（`fe-light` / `fe-dark`）。registerTheme 全局按名登记，
+     *  同页存在两种作用域时，调用方/判据必须能区分它们。 */
+    themeName: currentThemeName,
     defaults: defaults,
     create: create,
     /** 主题切换后重设（配合 theme-toggle.js 调用） */
     refresh: function (inst) {
       if (!inst) return;
-      var name = currentThemeName();
+      var ctx = scopeOf(inst.__feDom);
+      var name = currentThemeName(ctx);
       if (typeof window.echarts !== 'undefined' && window.echarts.registerTheme) {
-        window.echarts.registerTheme(name, theme(name));
+        window.echarts.registerTheme(name, theme(name, null, ctx));
       }
       // 🔴 主题名变了必须重建实例（ECharts 的主题在 init 时绑定）
       if (inst.__feDom) {
@@ -269,7 +342,7 @@
         inst.dispose();
         return create(inst.__feDom, opt);
       }
-      inst.setOption(defaults(inst.__feOpts), name);
+      inst.setOption(defaults(inst.__feOpts, ctx), name);
       return inst;
     },
   };

package/09-assets/scientific-plot/README.md

@@ -88,7 +88,8 @@ http://127.0.0.1:8000/09-assets/scientific-plot/demo.html
 
 ## 已知限制
 
-- 未在 iOS / Android 真机 WebView 上验证（与库整体一致）。
+- 未做过真机整页验收：图表在真实设备上的 DPR、字号、滚动表现都没有验过。
+  能力探针那 7 行只测 CSS 能力，不覆盖画布渲染。
 - 刻度标签未做"相邻标签重叠时自动抽稀"（对数轴跨大数量级时已按 10 的幂简化）。
 - 无数据点级别的无障碍替代（图表整体有 `aria-label`，逐点值需调用方在页面上另给文本等价说明，
   demo.html 第 5 节演示了做法）。

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

@@ -67,13 +67,6 @@
     return v.toFixed(p);
   }
 
-  function cssVar(name, fallback) {
-    if (typeof getComputedStyle !== 'function' || !document.documentElement) return fallback;
-    var v = getComputedStyle(document.documentElement).getPropertyValue(name);
-    v = v ? v.trim() : '';
-    return v || fallback;
-  }
-
   /* --------------------------------------------------------------- 比例尺 */
 
   /**

package/AGENTS.md

@@ -1,7 +1,8 @@
 # agentcss — for coding agents
 
-- **Contract (machine-readable):** `ai/components.json` — 40 components with root class, slots, variants, states, ARIA and file paths. Query it; never guess class names.
+- **Contract (machine-readable):** `ai/components.json` — 40 components with root class, slots, variants, states, ARIA, file paths, and **`printPolicy`** (what happens to this component on paper: `omit` / `expand` / `reveal` / `keep-together` / `allow-break`, plus a `pagination` flag). Query it; never guess class names — and never assume a component prints as it looks on screen.
 - **Known failure modes:** `ai/pitfalls.json`, or `npx agentcss ai pitfalls --json --component=<id>`.
+- **Print / PDF:** `npx agentcss ai pdf <page.html> --out page.pdf [--paper=a4|letter|a5] [--margin="18mm 15mm"] [--max-pages=N]`. `@page` belongs to the exporter, never to the library. To hold a document to paper standards use `ai check <doc.json> --medium=paper` — it then requires `pageBudget` and refuses `pagination:"server"` components.
 - **Query:** `npx agentcss ai components --json [--maturity=stable]` · `ai tokens --json [--set=dark]` · `ai tree --json`.
 - **Validate:** `npx agentcss ai validate <file> --schema=components --json`. Every subcommand accepts `--json`; failures print `{"ok":false,…}` and exit non-zero.
 - **Markup ground truth:** each component's `demo.html`. Restyle through tokens (CSS variables); never rewrite component selectors.