设置面板的 Esc 希望能只关最上层弹窗（嵌套 aria-modal 场景）

[mengge237]

想说的

设置里打开第三方弹窗（我这里是「会话归档管理」→ 预览某条会话）之后按 Esc，本来只想关弹窗，结果整个设置面板一起没了。想请 core 这边把 Escape 改成"只关最上层那个弹窗"。

为什么会这样

两边都单独看没错，叠一起就出问题了。

@deepseek-ai/dsh-client-ui-settings-general 里的 SettingsPanel：

useEffect(() => {
    const onKeyDown = (e) => {
        if (e.key === "Escape") onClose();
    };
    document.addEventListener("keydown", onKeyDown);
    ...
}, [onClose]);

@linxin666/dsh-session-archive 的 Modal 也是一模一样的写法：在 document 上挂 bubble 阶段的 keydown，收到 Escape 就 onClose()，既不 stopPropagation 也不看自己是不是最上层。同一次按键两个监听器都命中，于是弹窗和设置面板同时卸载。我在 0.1.2-rc.1 上量的：按一次 Esc，[role=dialog] 从 settings + 会话预览 直接变成 []。

建议

1. core 在 Escape 之前先看有没有嵌套的模态还开着，比如

if (document.querySelector('[role="dialog"][aria-modal="true"] [role="dialog"][aria-modal="true"]')) return;

这样即使第三方弹窗忘了 stopPropagation，设置面板也不会被顺带关掉。反过来说，插件弹窗该不该自己 stop 是另一回事，core 这边兜底更省事，因为插件不可能都指望得上。

2. 顺带一个更根本的：core 能不能出一个官方 Modal 原语（portal 挂到 body 上、焦点进入/归还、Esc 只关最上层、inert 处理背景），然后文档里写清楚"插件弹窗必须走它"？现在插件是就地渲染 fixed 遮罩，一旦祖先上有 backdrop-filter / transform 之类，fixed 就被收编进那个容器了——设置面板正好有（社区皮肤给它加了毛玻璃），结果弹窗底边被面板的 overflow: hidden 切掉，矮窗口下"关闭"按钮根本点不到，我是靠 CSS 把嵌套弹窗绑回容器才绕过去的。有官方原语的话这类问题能少一大截。

3. 小的体验问题：设置面板开着的时候，输入卡还按 hero 状态占着那么大高度（--dsh-composer-height 我这边看到 240 到 408px），弹窗是画在面板里的，两个叠一块儿中间特别挤。设置面板打开时能不能把 composer 收起一档，或者干脆不渲染。

复现环境：Windows，dsh web 0.1.2-rc.1，@linxin666/dsh-web-all 0.3.14（含 dsh-session-archive），Chromium 系浏览器。需要我在别分辨率上再验一遍的话说一声。

[argszero]

Verified against master — this is a real behavior and the fix is a small client-side change. packages/client/ui-primitives/src/Modal.tsx:43-47: every mounted Modal installs its own global document keydown listener and closes on Escape, with no awareness of other open modals. With nested aria-modal overlays (settings panel opens a sub-dialog), each layer's listener fires on the same keypress — so Esc closes more than the topmost layer.

The standard fix shape: a module-level modal stack (or a shared keydown dispatcher). Each Modal registers on mount / unregisters on unmount; the Escape handler acts only when the instance is at the top of the stack, and a close that removes the top re-enables the next layer's handler naturally. This keeps the current per-instance useEffect structure and only adds stack membership — no change to the close semantics (mask click + close button stay per-instance).

Worth also double-checking the accessibility contract while touching it: aria-modal implies the background is inert to screen readers, so matching the visual topmost-only behavior with a focus trap that moves to the new top when a layer closes is the a11y-complete version. Small, contained, client-side — a good first PR for anyone wanting to pick it up.

[mengge237]

谢谢核实，行号也对上了。我顺手把 npm 上那份 @deepseek-ai/dsh-client-ui-primitives@0.0.1-rc.1 解包看了下：Modal 里 createPortal 和 aria-modal 都在，但 focus / activeElement / tabIndex / inert 一个都搜不到，也没有任何堆栈概念 —— 所以你讲的 a11y 那段确实是现成的缺口，不只是 Esc 分层的事。同包里那个下拉 / popover 原语也是 document.addEventListener("keydown") 配 if (e.key === "Escape") onClose()，一模一样的写法；要是共享堆栈只收 Modal 不管它，Esc 关下拉的时候底下那个 Modal 照样会被一起收掉。

还有一点：我这台的依赖树里其实没装上这个包（dsh 0.1.2-rc.1），core 的设置面板是另抄了一份 keydown，社区插件那边又自己写了一份 Modal —— 所以就算原语修好了，实际在跑的那几份也还是各关各的。感觉真正的收益点可能是让这个包被用起来（哪怕先在插件文档里写一句"弹窗请用 ui-primitives 的 Modal，别自己挂 document keydown"）。

有个实际障碍想确认下：CONTRIBUTING 里写着目前不接受外部 PR（"we cannot accept external pull requests at the moment"），所以这条 good first PR 我没法提到这个仓库。这种小 patch 你们希望走哪儿？如果只是希望有人把设计写清楚，我可以把我本地那版思路整理出来贴在楼里 —— capture 阶段挂一个监听，只在确实存在嵌套 aria-modal 时拦下这一次 Escape 并交给最上层，第三方弹窗一行代码不改也能被兜住，我拿它验过四层高度的场景都正常。