agentcss 0.0.0-stage → 0.11.2

package/03-patterns/list/flip.js

@@ -0,0 +1,201 @@
+/* ============================================================================
+   frontend-lib / 03-patterns / list / flip.js
+   列表增删的 FLIP 动画
+
+   依赖：无
+   适用：精简档 / B / C
+
+   🔴 为什么自己写，不用 auto-animate：
+
+        项目：        auto-animate      自己写 FLIP
+        体积          ~8 KB             ~1.5 KB
+        协议尽调      必需              零风险
+        依赖风险      供应链/更新       无
+        能力          增删改 + 颜色 + 尺寸 + 表单值  只做"增删时其余项平滑移动"
+
+     列表 pattern 真正需要的只有最后一列那一项。
+     为不需要的能力引入第三方依赖，不划算。
+
+   FLIP 原理（四步，约 40 行）：
+     First  记录变化前的位置
+     Last   DOM 变化后记录新位置
+     Invert 用 transform 反向偏移回去（视觉上没动）
+     Play   过渡到 transform: 0（看起来平滑移动）
+
+   🔴 语法刻意用 ES5（无箭头函数 / const / let / 模板字符串）：
+      精简档 是 某项目 上的 WebView，版本不确定。
+   ========================================================================= */
+(function (global) {
+  'use strict';
+
+  /* ------------------------------------------------------------ 工具 */
+  function forceReflow(el) {
+    /* 强制浏览器重算布局并记录当前样式值。
+       FLIP 的第三步（Invert）靠它把"反向偏移"这个中间态真正记录下来；
+       少了这一步，浏览器会认为 transform "没变"而跳过过渡。
+
+       读 offsetHeight 会强制同步布局 —— 这正是我们要的"副作用"。
+       requestAnimationFrame **不能**替代它（rAF 不保证重排）。 */
+    return el.offsetHeight;
+  }
+
+  function idOf(el) {
+    /* 不用 dataset —— 兼容性更差的那个 API */
+    return el.getAttribute('data-flip-id');
+  }
+
+  function prefersReducedMotion() {
+    return global.matchMedia
+        && global.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  }
+
+  /* ------------------------------------------------------------ 核心 */
+  /**
+   * @param container  列表容器（它的**直接子元素**就是可动画项）
+   * @param mutate     修改 DOM 的函数
+   * @param opts       { enter: 淡入/上滑, leave: 淡出, duration: ms }
+   *
+   * 用法：
+   *   flip(listEl, function () { listEl.removeChild(row); });
+   */
+  function flip(container, mutate, opts) {
+    opts = opts || {};
+
+    var DURATION = opts.duration || 260;
+    var reduce = prefersReducedMotion();
+
+    /* --- First：记录每个项变化前的位置 --- */
+    var first = {};
+    var kids = container.children;
+    var i, el, id, box;
+
+    for (i = 0; i < kids.length; i++) {
+      el = kids[i];
+      id = idOf(el);
+      if (id) { first[id] = el.getBoundingClientRect(); }
+    }
+
+    /* --- 让调用方改 DOM --- */
+    mutate();
+
+    if (reduce) {
+      /* 🔴 reduced-motion：**减弱，不是归零**
+
+         之前这里直接 return，等于"完全跳过" —— 与本库 CSS 层的策略
+         （spinner 保留、骨架屏停止 = 减弱）自相矛盾。
+
+         正确的做法是按"是否构成前庭刺激"来分：
+           位移 / 缩放 / 旋转  → 有刺激，去掉
+           opacity 淡入淡出     → 无刺激，保留
+
+         所以 reduced-motion 下：其余项**直接落到新位置**（不做 FLIP），
+         新增项**仍然淡入**，只是不位移。
+      */
+      for (i = 0; i < container.children.length; i++) {
+        el = container.children[i];
+        id = idOf(el);
+        if (!id || first[id] !== undefined) { continue; }
+        el.style.opacity = '0';
+        el.style.transition = 'none';
+        /* 同样用强制重排而不是 rAF —— 与下面 FLIP 主流程保持一致 */
+        forceReflow(el);
+        el.style.transition = 'opacity ' + DURATION + 'ms linear';
+        el.style.opacity = '1';
+      }
+      return;
+    }
+
+    /* --- Last + Invert + Play --- */
+    kids = container.children;
+    for (i = 0; i < kids.length; i++) {
+      el = kids[i];
+      id = idOf(el);
+      if (!id) { continue; }
+
+      box = el.getBoundingClientRect();
+
+      if (first[id] === undefined) {
+        /* ---- 新增项：**只淡入，不位移** ----
+           🔴 修正：原来这里还加了 translateY(6px)。
+           点击"添加一条"时看到**文字重合了一瞬** —— 根因是：
+           新项一边向上位移一边淡入，而它下方的旧行正往下滑开，
+           两者在某一帧**交叉**，视觉上就是两行文字叠在一起。
+
+           位移是这里唯一制造交叉的要素，去掉它即可。
+           旧行照常 FLIP 滑开，新项原地淡入 —— 观感更干净。 */
+        el.style.opacity = '0';
+        el.style.transition = 'none';
+        forceReflow(el);
+        el.style.transition = 'opacity ' + DURATION + 'ms linear';
+        el.style.opacity = '1';
+        continue;
+      }
+
+      /* ---- 已有项：算出位移，反向偏移再过渡回 0 ---- */
+      var dx = first[id].left - box.left;
+      var dy = first[id].top - box.top;
+
+      if (dx === 0 && dy === 0) { continue; }   /* 没动就别白跑一趟动画 */
+
+      el.style.transition = 'none';
+      el.style.transform = 'translate(' + dx + 'px, ' + dy + 'px)';
+
+      /* 🔴🔴 修正一个**让动画完全不动**的经典错误（实测反馈"完全不动"）：
+
+         原写法是「下一帧把 transform 设成**同一个值**」——
+             el.style.transform = translate(dx,dy);
+             rAF(→ el.style.transform = translate(dx,dy));   ← 值没变！
+         浏览器看到 transform 没变化，**不播放过渡**，于是元素直接跳到新位置。
+
+         而且 rAF **不保证**触发布局重算，所以第一步的"反向偏移"可能根本没被记录。
+
+         正确做法（FLIP 标准流程）：
+             1. transition:none + 设反向偏移
+             2. **强制重排**（显式读一次布局，让浏览器记录当前值）
+             3. 设 transition
+             4. **把 transform 设回 ''（即 0）** —— 不是设成同样的偏移值
+      */
+      forceReflow(el);
+      el.style.transition = 'transform ' + DURATION + 'ms ease-out';
+      el.style.transform = '';                 /* 回到原位 = 视觉上"平滑滑过去" */
+
+      /* 过渡结束后清掉内联样式 —— 否则会污染 hover / 后续布局 */
+      global.setTimeout(function (node) {
+        return function () { node.style.transition = ''; };
+      }(el), DURATION + 20);
+    }
+  }
+
+  /* ------------------------------------------------------------ 退场动画
+     删除项不能直接 remove —— 那样其余项会"瞬间跳过去"，没有补间。
+     正确：先淡出并让它留在原位，等动画结束再真正移除。 */
+  function removeWithAnimation(container, el, done) {
+    var reduce = prefersReducedMotion();
+    var DURATION = 260;
+
+    if (reduce) {
+      /* 减弱，不是归零：**淡出保留**（opacity 无前庭刺激），
+         只去掉 scale 缩放。 */
+      el.style.transition = 'opacity ' + DURATION + 'ms linear';
+      el.style.opacity = '0';
+      global.setTimeout(function () {
+        if (el.parentNode) { el.parentNode.removeChild(el); }
+        if (done) { done(); }
+      }, DURATION);
+      return;
+    }
+
+    el.style.transition = 'opacity ' + DURATION + 'ms ease-in';
+    el.style.opacity = '0';
+    /* 轻微缩一下，给出"被移除"的反馈；不缩会像元素凭空消失 */
+    el.style.transform = 'scale(0.97)';
+
+    global.setTimeout(function () {
+      if (el.parentNode) { el.parentNode.removeChild(el); }
+      if (done) { done(); }
+    }, DURATION);
+  }
+
+  global.FLIP = { flip: flip, remove: removeWithAnimation };
+
+})(window);

package/03-patterns/list/list.css

@@ -0,0 +1,162 @@
+/* ============================================================================
+   frontend-lib / 03-patterns / list / list.css
+   列表：行布局 + 增删动画的样式支撑
+
+   依赖：01-tokens/tokens.css  +  02-primitives/button/button.css
+   版本：A ✅ / B ✅ / C ✅
+
+   配套：flip.js（增删动画，零依赖）
+   规范：不堆卡片、每屏一个焦点、用真实数据
+   ========================================================================= */
+
+.list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  border-top: 1px solid var(--border-decor);
+}
+
+.list__item {
+  display: flex;
+  align-items: center;
+  gap: var(--sp-3);
+  padding: var(--sp-3) var(--sp-4) var(--sp-3) calc(var(--sp-4) - 2px);
+
+  /* 🔴 hover 不跳动的关键：左侧线用 transparent **预留位**，
+     hover 时只改颜色。
+     如果用 border-inline-start: 2px solid transparent 然后改成 3px，或者
+     hover 时才加 border —— 内容会横移 1~2px，这就是"列表在抖"。 */
+  border-inline-start: 2px solid transparent;
+  border-bottom: 1px solid var(--border-decor);
+
+  transition: background-color var(--dur-fast) var(--ease-out),
+              border-inline-start-color var(--dur-fast) var(--ease-out);
+}
+
+@media (hover: hover) and (pointer: fine) {
+.list__item:hover {
+  background: var(--surface-sunken);
+  border-inline-start-color: var(--border-decor-str);
+}
+}
+/* 🔴 行内操作可聚焦时，整行给反馈。
+   只在 :focus-within（焦点进入行内）时给，不给整行加 tabindex ——
+   那样 Tab 会为每一行多停一次，键盘用户要按几十次才能穿过列表。 */
+.list__item:focus-within {
+  background: var(--surface-sunken);
+  border-inline-start-color: var(--accent);
+}
+
+/* 键盘 Tab 时行内按钮的焦点环（不加会看不见） */
+.list__actions .btn:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
+}
+
+/* ---------------------------------------------------------------- 主信息 */
+.list__main { flex: 1; min-width: 0; }   /* min-width:0 防长内容撑破 */
+
+.list__title {
+  display: block;
+  font-size: var(--fs-sm);
+  color: var(--text-primary);
+  /* 长公司名截断而不是换行 —— 换行会让行高跳变，破坏列表节奏 */
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.list__meta {
+  display: block;
+  font-size: var(--fs-xs);
+  color: var(--text-tertiary);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* ---------------------------------------------------------------- 数值列
+   🔴 涨跌色遵循中文用户习惯：**红涨绿跌**，与欧美相反。
+      这里不做"国际统一"，因为使用者是中国 A 股用户。 */
+.list__value {
+  font-size: var(--fs-sm);
+  white-space: nowrap;
+  color: var(--text-secondary);
+}
+.list__value--up   { color: var(--danger); }    /* 涨 = 红 */
+.list__value--down { color: var(--success); }  /* 跌 = 绿 */
+
+/* ---------------------------------------------------------------- 行内操作
+   默认隐藏：键盘用 focus-within 显示，鼠标用 hover 显示。
+   🔴 但**不要用 display:none** —— 那会让操作从 tab 顺序消失。
+      正确做法是保持可聚焦（opacity / visibility 都要配合）。 */
+.list__actions {
+  display: flex;
+  gap: var(--sp-2);
+  flex: none;
+  opacity: 0;
+  transition: opacity var(--dur-fast) var(--ease-out);
+}
+@media (hover: hover) and (pointer: fine) {
+.list__item:hover .list__actions,
+.list__item:focus-within .list__actions { opacity: 1; }
+}
+/* ============================================================================
+   窄屏：次信息换行，数值列右对齐
+   ========================================================================= */
+@media (max-width: 34rem) {
+  .list__item {
+    flex-wrap: wrap;
+    row-gap: var(--sp-1);
+  }
+  .list__actions { width: 100%; opacity: 1; }   /* 触屏没有 hover，必须常显 */
+}
+
+/* ============================================================================
+   排序时的一行提示（可选）
+   ========================================================================= */
+.list__note {
+  font-size: var(--fs-xs);
+  color: var(--text-tertiary);
+  padding: var(--sp-2) var(--sp-4);
+}
+
+/* ============================================================================
+   reduced-motion
+   =========================================================================
+   位移/颜色过渡全部关闭。
+   🔴 FLIP 的进出场动画在 JS 里已整体跳过（prefers-reduced-motion 判定），
+      这里关掉的是 hover 等常规微交互 —— 两者是不同层次，别漏。
+   ========================================================================= */
+@media (prefers-reduced-motion: reduce) {
+  .list__item,
+  .list__actions { transition: none; }
+}
+
+/* ============================================================================
+   反模式
+   =========================================================================
+   1. hover 时加 border / 改 padding
+      内容会横移 1~2px，列表"在抖"。正确做法：border 用 transparent 预留位，
+      hover 只改颜色。
+
+   2. 整行加 tabindex="0"
+      Tab 会为每一行多停一次。键盘用户穿过 20 行要按 20 次 Tab。
+      行内操作本身可聚焦就够了，用 :focus-within 给整行反馈。
+
+   3. 行内操作用 display:none / visibility:hidden
+      从 tab 顺序消失，键盘用户永远到不了"删除"按钮。
+      用 opacity + hover/focus-within 控制可见性。
+
+   4. 长文本直接换行
+      行高跳变，列表节奏被打乱。用 ellipsis 截断，完整内容走 title 属性。
+
+   5. 涨跌色按欧美习惯（绿涨红跌）
+      🔴 中国的 A 股用户习惯是**红涨绿跌**。做反了会被当成出错。
+
+   6. 窄屏仍然隐藏行内操作
+      触屏没有 hover，操作会彻底消失。窄屏必须常显。
+
+   7. 引入 auto-animate 这类库只为了做"增删时其余项平滑移动"
+      8 KB 换 40 行能做的事，还要承担协议尽调与供应链风险。见 flip.js 头部。
+   ========================================================================= */

package/03-patterns/nav/README.md

@@ -0,0 +1,225 @@
+# nav —— 页头 / 目录 / 移动端抽屉
+
+| 字段 | 内容 |
+|---|---|
+| **来源** | 原创。`toc.js` 是从 `04-recipes/longform` 内联脚本**提取并加固**的；`nav.js` 是从 demo/示例页**手抄了两遍**的抽屉逻辑抽出来的 |
+| **实测** | demo 三件事都能真机验证（页头/目录/抽屉）；抽屉的 22 条行为由 `05-audit/nav-drawer.js` 在浏览器里跑 |
+| **适用** | 精简档 / B / C，`toc.js` 与 `nav.js` 均为 ES5 |
+| **依赖** | `01-tokens/tokens.css` + `02-primitives/button/button.css` + `01-tokens/page.css`（页面骨架：`.wrap` / `.lede` / `.note`） + `01-tokens/typography.css` |
+| **规范** | 见本文件「状态切换」一节|
+
+---
+
+## 一个目录，两个全局
+
+`nav/` 里有**两个独立脚本、两个全局**：
+
+| 文件 | 全局 | 形态 | 自动初始化 |
+|---|---|---|---|
+| `nav.js` | `Nav` | attach（`Nav.attach(root)`） | **是**，扫 `[data-nav]` |
+| `toc.js` | `Toc` | direct（`Toc.init(opts)`） | 否，必须自己调 |
+
+它们**共用同一份 HTML**（页头 + 目录 + 抽屉）但**生命周期无关**：
+抽屉常常用不上目录，目录也可能出现在没有抽屉的长文页里。所以不合并成一个脚本。
+
+⚠️ AI 契约（`ai/components.json`）里 `nav` 这个组件记的是 `global: "Nav"` +
+`globalAlso: [{Toc}]` —— 一个组件目录可以导出第二个全局。
+`05-audit/autoinit-gate.py` 会按这张清单核对 `API.md` 的表，
+少记一个就会报「表里出现了库里没有的全局」。
+
+---
+
+## 抽屉行为层：`nav.js`（可选，但没有它抽屉就是死的）
+
+```html
+<header class="nav" data-nav>
+  <button class="nav__toggle" aria-expanded="false" aria-controls="nav-list">…</button>
+  <ul class="nav__list" id="nav-list">…</ul>
+  <div class="nav__scrim"></div>      <!-- 可省，缺了 JS 自己建 -->
+</header>
+<script src="nav.js"></script>         <!-- 有 data-nav 就自动初始化 -->
+```
+
+`nav.css` 只定义了**状态长什么样**（`[data-state="open"]` / `aria-expanded`），
+从没规定**谁来切**。所以在这之前，每个使用者都要抄 60 行 —— 抄出来的版本
+各有各的漏。现在这一层在库里，并且被门禁按 22 条判据盯着。
+
+### 🔴 抄出来的版本里那个 bug：`aria-hidden` 打在了祖先上
+
+旧 demo 的写法是「把 body 的每个子元素都 `aria-hidden`，跳过 list/scrim/toggle」。
+问题：`<header class="nav">` 是 list 的**祖先**，它不在跳过名单里 ⇒
+整块 `<header>` 被 `aria-hidden="true"` 包住，**抽屉自己也跟着对读屏消失**。
+
+而它"看起来完全正常"：截图正常、像素比对正常、键盘 Tab 也正常。
+**只有用读屏打开菜单才会发现里面一个字都读不出来。**
+
+`nav.js` 的判据是「跳过**包含**导航自身的节点」，而不是「跳过这三个元素」。
+
+### 🔴 为什么复用 `drawer.js` 会错
+
+`03-patterns/drawer/drawer.js` 的 `Drawer.open()` **自己建 DOM**（new aside、
+塞进 body、关了就删）。而导航列表在文档里本来就有一份，桌面端还要用它横排。
+**生命周期相反**（即用即毁 vs 常驻），所以不共用实现，只共用**核**：
+`emit` / `focus-return` / `dismissable` 三块与 `drawer.js` 逐行同源（`gen-behavior.py` 保证）。
+
+### 🔴 断点不写数字
+
+"窗口变宽就关掉"的判据是**汉堡按钮还在不在**（`offsetParent !== null`），
+不是 `window.innerWidth > 768`。CSS 里改一个断点值，写死数字的 JS 会**静默错位**。
+
+### 事件
+
+`fl-nav-open` / `fl-nav-close`（`detail = { root }`）。自动初始化不接回调
+—— 要收通知请听事件（与 `tabs.js` 同一条纪律）。
+
+---
+
+## 目录高亮：`toc.js`
+
+```js
+Toc.init({ links: '#toc-list .toc__link', sections: 'main h2[id]' });
+```
+
+返回一个取消函数（解绑事件）。
+
+### 🔴 为什么不用 `IntersectionObserver`（实测到 bug）
+
+第一版用的是 `IntersectionObserver` + `rootMargin: '-10% 0px -70% 0px'`，
+靠 `seen[id] = isIntersecting` 增量维护当前节。
+
+**实测反馈"导航不跟随文章移动"。** 根因：
+
+> **滚到两个 section 之间时，观察区里一个 section 都没有**
+> ⇒ `seen` 全为 false ⇒ 不调 `mark()` ⇒ 高亮停在上一个不动。
+
+**这不是边界情况，是常态**——用户大部分时间就滚在两节之间。
+
+现在统一用计算：`取最后一个 offsetTop <= 滚动位置 + 100px 的 section`。
+**任何滚动位置都有确定答案**，不会出现"都不在观察区"的状态。
+
+**为什么不用 IO 省 CPU**：两者成本其实一样——`scroll` 监听也只在**滚动时**执行
+（已用 `rAF` 节流），不滚动时都不跑。为了一个"看起来更优"的方案换正确性风险，不划算。
+
+### ⚠️ `offsetTop` 的前提
+
+它相对于 **`offsetParent`**。若把目录放在一个 `position: relative` 的容器里，
+`offsetTop` 会是相对那个容器的值，与 `pageYOffset` 不可比 ⇒ **高亮会错位**。
+
+**目录所在的祖先链上不要出现 `position: relative/absolute`。**
+
+### 前提：目录项与标题 id 一一对应
+
+```html
+<h2 id="mem">…</h2>          ← 标题必须有 id
+<a class="toc__link" href="#mem">…</a>   ← 目录指向它
+```
+
+少一个，**那一项永远不会被高亮**。`refs.py` 会静态抓这个错。
+
+---
+
+---
+
+## 目录的 sticky 必须在库里，不在 demo 里
+
+🔴 第一版这条只写在 demo 的内联 `<style>` 里，**任何引了 `nav.css` 的页面都没有 sticky**
+——目录随正文滚出视口，"跟着走"这个最基本的效果没有。
+
+**布局规则写在 demo 里 = 分层崩了。** 现在 `nav.css` 里：
+
+```css
+@media (min-width: 60rem) {
+  .toc { position: sticky; top: 76px; align-self: start; }
+}
+```
+
+- `top` 要**大于页头高度**（56px + 20px 留白），否则会停在页头下面被遮住
+- `align-self: start` **必须写** —— grid 子项默认 `stretch`，元素被拉高后 sticky 无处可动
+
+---
+
+## 抽屉：五条判据（都来自 08 规范）
+
+### 1. 只动 `transform`，不动 `width/left/top`
+
+```css
+.nav__list { transform: translateX(100%); transition: transform 180ms; }
+.nav__list[data-state="open"] { transform: translateX(0); }
+```
+
+动 `width` 会引起重排，页面抖一下。
+
+### 2. 打开时背景必须锁
+
+视觉上是覆盖层，逻辑上也要是模态——**两边必须一致**。
+否则用户能 Tab 到抽屉外面看不见的地方。
+
+### 3. 焦点必须移进抽屉，并且**关闭后回到汉堡按钮**
+
+丢了焦点，键盘用户就不知道自己在哪了。
+
+### 4. Esc 必须能关
+
+这是唯一"所有人都知道"的操作，不能只靠点遮罩。
+
+### 5. 窗口变宽时自动关掉
+
+否则抽屉会留在打开状态，而桌面布局下 `nav__list` 是横排的——
+用户会看到一个"开着但不对"的菜单。
+
+---
+
+## 三个无障碍细节
+
+| 做法 | 原因 |
+|---|---|
+| 跳过链接用 `transform` 移出视口，**不用 `display:none`** | `display:none` 会把它移出 tab 顺序，键盘用户 Tab 不到 |
+| 当前页用 `aria-current="page"` | 屏幕阅读器会播报"当前页面"，自定义 class 它不知道 |
+| 目录高亮用 `aria-current="true"` | 表示"在当前范围内的当前位置"，目录高亮通行做法 |
+
+---
+
+## 汉堡按钮的三条线怎么变 X
+
+```
+默认：  ─────  三条线
+        i::before / i::after 上下偏移 ±5.5px
+
+展开：  i 自身 rotate(45deg)      → 变成 /
+        i::before translateY + rotate(-90deg) → 变成 \
+        i::after opacity 0        → 消失
+```
+
+**为什么偏移量是 5.5px**：线宽 1.5px，中心间距 11px，所以偏移 5.5px 让它们重合到中心。
+这个数是算出来的，不是估的。
+
+---
+
+## 反模式
+
+- ❌ **抽屉展开时动 `width` / `left` / `top`** —— 引起重排，页面抖
+- ❌ **抽屉打开后背景仍可 Tab / 可点** —— 视觉是覆盖层，逻辑不是模态
+- ❌ **汉堡按钮小于 44px** —— 触摸目标硬下限
+- ❌ **当前页指示用自定义 class 而非 `aria-current`** —— 屏幕阅读器不知道
+- ❌ **目录项允许换行** —— 行高跳变，目录看着散
+- ❌ **没有 IntersectionObserver 就不做高亮** —— 目录变成死链接
+- ❌ **跳过链接用 `display:none`** —— 移出 tab 顺序，键盘到不了
+- ❌ **页头 sticky 但没背景色** —— 内容从下面透出来像重影
+
+---
+
+## 门禁
+
+| 项 | 能否机械检查 |
+|---|---|
+| CSS 引用完整性 | ✅ `refs.py` |
+| 状态切换的叠放/占位/溢出 | ✅ `switch.py` |
+| 焦点管理、Esc、背景锁、点遮罩、变宽自关 | ✅ `05-audit/nav-drawer.js`（浏览器 + 键盘，22 条） |
+| 读屏里到底听到了什么 | ❌ **必须真机开读屏** |
+| 视觉上别扭不别扭 | ❌ **必须真机** |
+
+🟡 0.11.2 之前这里写的是「焦点、Esc、背景锁**静态检查一个都查不出来**，必须真机」。
+那句话当时是对的，但它描述的是一种**可以修的**状态 —— 现在这三件事由
+`nav-drawer.js` 在真浏览器里跑（含连续 8 次 Tab 的焦点陷阱、Esc 后焦点归位、
+`aria-hidden` 是否误伤祖先）。**仍然查不出来的是"读屏实际播报什么"**：
+无头浏览器没有语音输出，`accessibility.snapshot()` 也只能读到树，读不到播报。