[Bug Report] Web UI 弹层：焦点可逃逸出 aria-modal 对话框，一次 Escape 同时关闭多层弹层（各弹层独立监听、无 stack 协调）

[DRAG0NM]

摘要

Web UI 的弹层没有统一的焦点与 Escape 协调：primitives Modal 与 Settings 面板（SettingsPanel）是两套独立实现，各自向 document 注册自己的 keydown 监听器（一个 Escape 事件会触发所有弹层的 onClose），且两者都没有任何焦点圈禁（无 Tab 循环、无背景 inert）——Shift+Tab 可以把焦点移出 aria-modal="true" 对话框到背后控件，关闭后焦点也不会恢复到触发元素。

复现步骤

1. 打开 Web UI（127.0.0.1:3080），打开 Settings（Agent presets 面板）。
2. 点击 Copy Standard 打开 copy-preset 弹窗（叠加在 Settings 之上）。
3. 焦点在标识输入框时按 Shift+Tab 两次：焦点依次移到 copy 弹窗的 Close、再移到 Settings 面板背后的"关闭详情"控件 —— 焦点逃逸出对话框。
4. 按一次 Escape：copy-preset 弹窗 和 Settings 面板同时关闭 —— 一个 Escape 事件关闭了两层。

社区已复现（Windows 10, Chromium, commit 47f9438）。预期：Tab 循环圈禁在顶层弹窗内；Escape 只关闭最顶层；关闭后焦点回到触发元素。

根因（源码定位，rc.6）

1. primitives Modal：独立 document 监听 + 无焦点管理 — @deepseek-ai/dsh-client-ui-primitives/lib/index.js：

   • L1983-1992：useEffect 中 document.addEventListener("keydown", onKeyDown)，if (e.key === "Escape") onClose() —— 每个 Modal 实例挂载期间都占用 document 级监听；
   • L1994-2034：渲染树只有 role="dialog" / aria-modal="true"（L2003-2004），没有焦点圈禁逻辑、没有对背景层的 inert/aria-hidden 处理、没有关闭后的焦点恢复。

2. Settings 面板（SettingsPanel）：另一套同样的独立实现 — @deepseek-ai/dsh-client-ui-settings-general/lib/client.js：

   • L100-108：同样在 useEffect 中 document.addEventListener("keydown", onKeyDown)、Escape → onClose（L94-95 注释明示 "document-level Escape (mounted only while open)"）；
   • L113-124：自定义 role="dialog" + aria-modal="true" 面板，同样无 Tab 循环（仅在打开时聚焦一次 close 按钮，L110-112）。

3. 两个监听器同时收到同一个 Escape 事件：Settings 面板与 copy-preset Modal 各自持有 document keydown 监听，事件冒泡到 document 后两处 onClose 都被调用 → 一层 Escape 关闭两层（与复现完全吻合）；两个弹层都没有 Tab 焦点圈禁 → 焦点自由移出对话框（与复现完全吻合）。

建议修复

方案 A（推荐）· 引入全局弹层栈协调：一个共享的 modal stack 服务/context —— 每个弹层注册进栈；Escape 只派发到栈顶弹层；焦点圈禁（Tab/Shift+Tab 在栈顶 dialog 内循环）、打开时聚焦首个可聚焦元素、关闭后把焦点还给触发元素。SettingsPanel 与 primitives Modal 都接入该栈，消除两套各自为政的监听。

方案 B · 分别补齐两处实现：primitives Modal 增加焦点陷阱 + 打开聚焦/关闭恢复；SettingsPanel 同步改造。改动局部但两处仍需保持一致（协调层缺失问题依旧，后续新弹层还会重蹈覆辙）。

方案 C · 背景 inert + 顶层 Escape 拦截：弹层打开时给背景层设 inert（阻止焦点进入，缓解逃逸）；Escape 监听改为"仅当自己是栈顶时响应"。可作为最小补丁，但焦点恢复与栈管理仍需 A 的方案才能完整。

影响

• 键盘可达性：aria-modal="true" 语义被破坏——屏幕阅读器/键盘用户焦点可进入背后控件，与无障碍契约不符；
• 误操作：一次 Escape 关闭多层弹窗（用户以为只关了最上层），未保存的编辑内容可能随层一起丢失；
• 架构风险：两套独立弹层实现继续分化（本报告即证据），后续 UI 弹层仍会重复出现同类问题。

环境

• 源码定位：0.1.0-rc.6（npx 缓存安装包，Node v24.16.0，Windows 11）
• 原报告：Modal focus can escape to the page, and one Escape closes nested dialog layers #938（Windows 10, Chromium, commit 47f9438 实测复现）

验证材料

• 社区复现步骤（Shift+Tab 两次逃逸 + 一次 Escape 关两层）与预期行为；
• rc.6 源码逐行核对：dsh-client-ui-primitives/lib/index.js L1983-2034 与 dsh-client-ui-settings-general/lib/client.js L97-124；
• 机制推演：两个独立 document keydown 监听 → 同一 Escape 事件触发两次 onClose；两处均无 Tab 循环 → 焦点可逃逸。

---

First analysis of discussion #938. Happy to open a PR with fix option A.