@yfwu2020/dsh-selection-explain 0.10.1 → 0.10.3

package/README.md

@@ -8,7 +8,7 @@ DSH 中的翻译、上下文解读与语音追问。
 
 [快速安装](#install) · [语音输入](#voice) · [功能一览](#read) · [使用与设置](#settings)
 
-`DSH 插件` · `v0.10.1` · `MIT`
+`DSH 插件` · `v0.10.3` · `MIT`
 
 </div>
 
@@ -103,11 +103,11 @@ dsh plugin --profile web add @yfwu2020/dsh-selection-explain
 <details>
 <summary>安装 Release 构建包</summary>
 
-将下载的 `.tgz` 放到当前目录，以 v0.10.1 为例：
+将下载的 `.tgz` 放到当前目录，以 v0.10.3 为例：
 
 ```bash
 mkdir -p ~/.dsh/plugins/dsh-selection-explain
-tar -xzf yfwu2020-dsh-selection-explain-0.10.1.tgz -C ~/.dsh/plugins/dsh-selection-explain --strip-components=1
+tar -xzf yfwu2020-dsh-selection-explain-0.10.3.tgz -C ~/.dsh/plugins/dsh-selection-explain --strip-components=1
 dsh plugin --profile web add ~/.dsh/plugins/dsh-selection-explain
 ```
 
@@ -153,6 +153,16 @@ dsh plugin --profile web remove @yfwu2020/dsh-selection-explain
 | 界面 | 语音卡片收尾、侧边栏网页划词与悬浮胶囊 |
 | 数据 | 保留多少条最近解读 |
 
+### 与完整视图、最近会话共存（0.10.2）
+
+解读小窗使用自己的浮层，显示在最近会话列表和完整视图工作面板上方，空白区域仍可点击原界面。在完整视图里，解读插件自行隐藏悬浮胶囊；返回分栏后恢复。
+
+聊天与解读可以同时打开。与 `dsh-full-view` **0.1.6**、`dsh-recent-sessions` **0.2.3** 配合时，`Esc` 先退出最后操作的小窗；点击两窗之外后先退解读，再按一次收起聊天。此次调整需一起更新两个插件，未改变 Harness 的公共浮层或设置。
+
+### 快捷键与 Esc 层级（0.10.3）
+
+模型菜单收起后不再被 DSH 识别为弹层，避免设置等快捷键失效。官方设置等模态浮层打开时，`Esc` 优先交给官方浮层处理，保留解读小窗、插件设置抽屉、模型菜单和语音卡；官方浮层关闭后，再按 `Esc` 继续退出插件层级。
+
 ## 数据与使用范围
 
 选中文字、必要的前后文，以及开启的会话背景会交给你配置的模型。可在设置中关闭会话背景或工具调用。

package/lib/client.js

@@ -4,9 +4,9 @@
  * 交互：在页面任意位置选中文字 → 选区末端浮出「解读」按钮 → 点击弹出面板，
  * 面板流式显示两节：① 专业中英翻译 ② 这段文字在当前上下文中的含义详解。
  *
- * 挂载点走官方 shell.overlay 槽（帧级浮层：三栏之外、滚动容器之外、默认
- * click-through，条目自己 opt-in pointer-events）——因此 UI 不会挡住 App。
- * 浮标与面板用 position:fixed 定位到选区坐标，DOM 归 shell.overlay 条目所有。
+ * 官方 shell.overlay 槽管理挂载生命周期；界面由插件自己挂到 body 的独立根。
+ * 根层固定为 70，越过全屏工作面板，不改写宿主公共浮层。空白区域鼠标穿透。
+ * 浮标与面板继续用 position:fixed 定位到选区坐标。
  *
  * 本文件是 DSH 客户端 bundle 的源文件（ModuleLoader 懒加载 CJS 表格式）：
  * 顶层只注册工厂，真正的副作用（React 组件、DOM/CSS、监听）都在 factory 被
@@ -435,9 +435,10 @@ window.__ModuleLoader__.load({
       //   --sel-fill(-fg)  实心块：浮标按钮 / 发送键 / 结论条标签——块上文字另算一套，
       //                    否则青底配白字只有 3.6（不达标），浅色下换成深青 5.4、深色下反白 7.4
       // 变量挂在浮层容器上 → 浮标与面板共用；深浅由**面板实际底色**决定（data-theme）。
-      '.dsh-sel-layer{--sel-a1:#0d9488;--sel-a1-text:#0f766e;--sel-a2:#0d9488;--sel-a2-text:#0f766e;',
+      '.dsh-sel-layer{position:fixed;inset:0;z-index:70;pointer-events:none;--sel-a1:#0d9488;--sel-a1-text:#0f766e;--sel-a2:#0d9488;--sel-a2-text:#0f766e;',
       '--sel-fill:#0f766e;--sel-fill-fg:#ffffff;',
       '--sel-a2-soft:color-mix(in srgb,var(--sel-a2) 12%,transparent);--sel-a1-soft:color-mix(in srgb,var(--sel-a1) 10%,transparent)}',
+      '.dsh-sel-layer[data-full-view] .dsh-sel-pill{display:none!important}',
       '.dsh-sel-layer[data-theme=dark]{--sel-a1:#4ecdc4;--sel-a1-text:#6fe3d8;--sel-a2:#4ecdc4;--sel-a2-text:#6fe3d8;',
       '--sel-fill:#4ecdc4;--sel-fill-fg:#052b26;',
       '--sel-a2-soft:color-mix(in srgb,var(--sel-a2) 16%,transparent);--sel-a1-soft:color-mix(in srgb,var(--sel-a1) 16%,transparent)}',
@@ -2492,9 +2493,10 @@ window.__ModuleLoader__.load({
       styleEl.textContent = CSS
       document.head.appendChild(styleEl)
 
-      /** 浮层容器：挂在 shell.overlay 条目里，自身 click-through。 */
+      /** 自有浮层根：位于 body，公共父层的堆叠上下文不影响它。 */
       var layer = el('div', 'dsh-sel-layer')
       layer.style.pointerEvents = 'none'
+      layer.setAttribute('data-dsh-floating-owner', 'explanation')
 
       var button = el('button', 'dsh-sel-btn')
       button.type = 'button'
@@ -2646,7 +2648,7 @@ window.__ModuleLoader__.load({
       modelPill.appendChild(modelPillTier)
       modelPill.appendChild(el('span', 'dsh-sel-picker-caret', '▼'))
       var modelMenu = el('div', 'dsh-sel-pickermenu')
-      modelMenu.setAttribute('role', 'menu')
+      // role 随开合同步：DSH 按 [role="menu"] 判定弹层，不检查 CSS 可见性。
 
       // ── 录音行（与主会话 ui-voice-input 同一套结构）──
       //   [✕ 取消] [实时波形 / 状态文案] [■ 停止 或 行内动作] …… [↑ 发送（原位不动）]
@@ -3758,10 +3760,27 @@ window.__ModuleLoader__.load({
       layer.appendChild(historyList)
 
       /**
-       * 注册进官方 shell.overlay 槽（帧级浮层）。
-       * React 组件只负责把 layer 容器挂进浮层；浮标/面板由上面的命令式代码管理，
-       * React 不接管它们的子树（容器本身无 children，不会被 diff 清空）。
+       * 官方槽仅保留不可见的生命周期锚点；界面根由本插件挂到 body。
+       * 稳定 ref 避免 React 重渲染时摘挂根节点、丢失输入焦点。
        */
+      function syncFullViewLayer() {
+        var fullView = !!document.querySelector('[data-dsh-full-view]')
+        if (fullView !== layer.hasAttribute('data-full-view')) {
+          if (fullView) layer.setAttribute('data-full-view', '')
+          else layer.removeAttribute('data-full-view')
+        }
+      }
+      function mountFloatingLayer(node) {
+        if (node) {
+          if (layer.parentNode !== document.body) document.body.appendChild(layer)
+          syncFullViewLayer()
+        } else if (layer.parentNode) layer.parentNode.removeChild(layer)
+      }
+      var fullViewObserver = null
+      if (typeof MutationObserver === 'function') {
+        fullViewObserver = new MutationObserver(syncFullViewLayer)
+        fullViewObserver.observe(document.body, {subtree:true, childList:true, attributes:true, attributeFilter:['data-dsh-full-view']})
+      }
       /** 开窗后"还没聚焦过输入框"（见 focusComposerOnce）。 */
       var askFocusPending = false
       /** 调试：最后一次"没聚焦"卡在哪一步（-1 表示聚焦成功）。 */
@@ -3780,16 +3799,14 @@ window.__ModuleLoader__.load({
               },
             }, function SelectionExplainLayer() {
               return React.createElement('div', {
-                className: 'dsh-sel-mount',
-                style: { pointerEvents: 'none' },
-                ref: function (node) {
-                  if (node && layer.parentNode !== node) node.appendChild(layer)
-                },
+                className: 'dsh-sel-anchor',
+                style: { display: 'none', pointerEvents: 'none' },
+                ref: mountFloatingLayer,
               })
             })
           })
         } catch (error) {
-          // 槽注册失败不应把整页插件装载一起拖垮：降级为仅报错（面板挂在浮层外不可见）
+          // 槽注册失败仅报错，自有界面根保持未挂载，不影响其他插件。
           console.error('[dsh-selection-explain] shell.overlay 槽注册失败：', error)
         }
       } else {
@@ -9467,6 +9484,7 @@ window.__ModuleLoader__.load({
        */
       var offVoiceEscape = listen(document, 'keydown', function (event) {
         if (event.key !== 'Escape' || !vcardState.open || event.defaultPrevented) return
+        if (document.querySelector('[role="dialog"][aria-modal="true"]')) return
         event.preventDefault()
         event.stopPropagation()
         vcardState.suppress = true
@@ -9919,11 +9937,13 @@ window.__ModuleLoader__.load({
 
       function closeModelMenu() {
         modelMenu.setAttribute('data-open', '0')
+        modelMenu.removeAttribute('role')
         modelPill.setAttribute('aria-expanded', 'false')
       }
 
       function openModelMenu() {
         modelMenu.setAttribute('data-open', '1')
+        modelMenu.setAttribute('role', 'menu')
         modelPill.setAttribute('aria-expanded', 'true')
         renderModelMenu()
         loadModelCatalog(false).then(function () {
@@ -9945,7 +9965,7 @@ window.__ModuleLoader__.load({
         event.stopPropagation() // 菜单内部点击不要触发"点到外面"
       })
       var offModelKeys = listen(modelMenu, 'keydown', function (event) {
-        if (event.key === 'Escape') closeModelMenu()
+        if (event.key === 'Escape' && !document.querySelector('[role="dialog"][aria-modal="true"]')) closeModelMenu()
       })
 
       // —— 网页模式开关 ——
@@ -10123,6 +10143,9 @@ window.__ModuleLoader__.load({
 
       var offKeyDown = listen(document, 'keydown', function (event) {
         if (event.key !== 'Escape' || !panelOpen || event.defaultPrevented || event.isComposing || event.keyCode === 229) return
+        // 官方模态浮层的 Esc 在冒泡阶段处理；capture 不消费，先让官方设置等浮层退出。
+        // 插件面板和设置抽屉是非模态 dialog，不带 aria-modal，不会命中这里。
+        if (document.querySelector('[role="dialog"][aria-modal="true"]')) return
         // 完整视图记录最后点击/操作的小窗；不能只看可能停在另一窗的键盘焦点。
         var fullViewFrame = document.querySelector('[data-dsh-full-view]')
         if (fullViewFrame) {
@@ -12127,6 +12150,7 @@ window.__ModuleLoader__.load({
             }
             pillObserver = null
           }
+          if (fullViewObserver) fullViewObserver.disconnect()
           if (typeof offSlot === 'function') offSlot()
           // 划词桥：摘观察者与消息监听，并把我们自己建的预览 blob 全部回收
           if (bridgeScanId) clearTimeout(bridgeScanId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yfwu2020/dsh-selection-explain",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "DSH 划词解读：选中文字浮出按钮，点击弹窗流式显示专业中英翻译 + 该文字在当前上下文中的含义详解",
   "type": "module",
   "main": "./lib/index.js",

package/scripts/smoke-panel.mjs

@@ -264,7 +264,19 @@ async function main() {
     check('插件装载（槽注册 + apply）', !!registration && registration.options.id === '@yfwu2020/dsh-selection-explain', registration && registration.options.id)
     registration.component().props.ref(mount)
     hook = window.__dshSelectionExplain
-    check('浮层挂进 mount', !!document.querySelector('.dsh-sel-layer'), '')
+    check('解读自有浮层已挂载', !!document.querySelector('.dsh-sel-layer'), '')
+    var ownedLayer = document.querySelector('.dsh-sel-layer')
+    check('解读使用 body 自有根，公开归属且空白穿透', ownedLayer.parentNode === document.body && ownedLayer.getAttribute('data-dsh-floating-owner') === 'explanation' && getComputedStyle(ownedLayer).pointerEvents === 'none', '')
+    check('解读独立根越过完整视图工作面板', Number(getComputedStyle(ownedLayer).zIndex) > 60, getComputedStyle(ownedLayer).zIndex)
+    var modeFrame = document.createElement('div')
+    document.body.appendChild(modeFrame)
+    modeFrame.setAttribute('data-dsh-full-view', '')
+    await sleep(40)
+    check('解读自身响应完整视图并隐藏胶囊', getComputedStyle(document.querySelector('.dsh-sel-pill')).display === 'none', '')
+    modeFrame.removeAttribute('data-dsh-full-view')
+    await sleep(40)
+    check('返回分栏由解读自身恢复胶囊', getComputedStyle(document.querySelector('.dsh-sel-pill')).display !== 'none', '')
+    modeFrame.remove()
   } catch (error) {
     check('插件装载（槽注册 + apply）', false, error && error.message)
     finish()
@@ -1492,8 +1504,57 @@ async function main() {
     hook.open('模型菜单勾选', '', '菜单冒烟')
     await waitFor(function () { return hook.state().phase === 'done' }, 8000)
     await hook.loadModels(true)
+    var modelNodes = hook.modelNodes()
+    // DSH 按属性判定弹层，不检查 CSS 可见性（Issue #1）。
+    var modalSelector = '[role="dialog"][aria-modal="true"], [role="menu"]'
+    function modelMenuOwnsShortcuts() {
+      return Array.from(document.querySelectorAll(modalSelector)).includes(modelNodes.menu)
+    }
+    function checkModelMenuClosed(reason) {
+      check(reason + '：模型菜单不再占用 DSH 快捷键',
+        !modelMenuOwnsShortcuts() && modelNodes.menu.getAttribute('data-open') !== '1' &&
+          modelNodes.pill.getAttribute('aria-expanded') === 'false')
+    }
+    checkModelMenuClosed('初始收起')
+    // 官方 useModalLayer 在 document 冒泡阶段处理 Esc；插件 capture 必须让行。
+    function checkHostEscapeFirst(target, label) {
+      var hostSettings = document.createElement('div')
+      hostSettings.setAttribute('role', 'dialog')
+      hostSettings.setAttribute('aria-modal', 'true')
+      hostSettings.setAttribute('data-shortcut-modal', 'settings')
+      var hostInput = document.createElement('input')
+      hostSettings.appendChild(hostInput)
+      document.body.appendChild(hostSettings)
+      function dismissHost(event) {
+        if (event.key !== 'Escape' || event.defaultPrevented) return
+        event.preventDefault()
+        hostSettings.remove()
+      }
+      document.addEventListener('keydown', dismissHost)
+      try {
+        var event = new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })
+        ;(target || hostInput).dispatchEvent(event)
+        check(label + '：Esc 到达官方浮层并只关闭官方设置',
+          event.defaultPrevented && !hostSettings.isConnected && panel.style.display === 'flex')
+      } finally {
+        document.removeEventListener('keydown', dismissHost)
+        hostSettings.remove()
+      }
+    }
+    var escapeModeFrame = document.createElement('div')
+    escapeModeFrame.setAttribute('data-dsh-full-view', '')
+    escapeModeFrame.setAttribute('data-dsh-active-floating-window', 'explanation')
+    for (var fullViewMode of [false, true]) {
+      if (fullViewMode) document.body.appendChild(escapeModeFrame)
+      var modeLabel = fullViewMode ? '完整视图' : '普通分栏'
+      checkHostEscapeFirst(null, modeLabel + '／焦点在官方设置')
+      checkHostEscapeFirst(document.querySelector('.dsh-sel-askbox'), modeLabel + '／焦点仍在解读输入框')
+    }
+    escapeModeFrame.remove()
     hook.openModel()
     await sleep(120)
+    check('模型菜单展开时占用 DSH 快捷键',
+      modelMenuOwnsShortcuts() && modelNodes.pill.getAttribute('aria-expanded') === 'true')
     var menu = hook.modelNodes().menu
     var rows = Array.prototype.slice.call(menu.querySelectorAll('.dsh-sel-pickerrow'))
     check('模型菜单列出 3 个模型（含同名 id 的另一 provider）', rows.length === 3, String(rows.length))
@@ -1517,7 +1578,24 @@ async function main() {
     var rowBox = onRows[0] ? onRows[0].getBoundingClientRect() : null
     check('打勾那一行仍是单行（高度不超过 30px，没折成两行）',
       !!rowBox && rowBox.height <= 30, rowBox ? Math.round(rowBox.height) + 'px' : '没找到那一行')
+
+    checkHostEscapeFirst(modelNodes.menu, '模型菜单仍展开')
+    check('官方设置关闭时保留插件模型菜单', modelNodes.menu.getAttribute('data-open') === '1')
+
+    clickOn(modelNodes.pill)
+    checkModelMenuClosed('再次点击胶囊')
+    hook.openModel()
+    modelNodes.menu.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    checkModelMenuClosed('按 Esc')
+    hook.openModel()
+    document.getElementById('docp').dispatchEvent(new MouseEvent('mousedown', { bubbles: true }))
+    checkModelMenuClosed('点击菜单外部')
+    hook.openModel()
+    clickOn(modelNodes.menu.querySelector('.dsh-sel-pickerrow'))
+    checkModelMenuClosed('选择模型')
+    hook.openModel()
     hook.close() // 关窗会顺手收起模型菜单
+    checkModelMenuClosed('关闭解读面板')
     await sleep(30)
   }
 

package/scripts/test-client.mjs

@@ -103,6 +103,9 @@ class FakeEl {
   removeAttribute(key) {
     delete this.attrs[key]
   }
+  hasAttribute(key) {
+    return this.getAttribute(key) !== null
+  }
   getAttribute(key) {
     return this.attrs[key] ?? null
   }
@@ -1242,7 +1245,10 @@ const mount = new FakeEl('div')
 const element = registration.component()
 assert('浮层组件返回 React 元素', !!element && element.type === 'div')
 element.props.ref(mount)
-assert('layer 容器已挂进浮层', mount.children.length === 1 && mount.children[0].className === 'dsh-sel-layer')
+const floatingLayer = body.children.find((c) => c.className === 'dsh-sel-layer')
+assert('界面挂在 body 自有根，不提升公共槽', !!floatingLayer && floatingLayer.parentNode === body && mount.children.length === 0)
+assert('自有根声明公开的小窗归属', floatingLayer && floatingLayer.getAttribute('data-dsh-floating-owner') === 'explanation')
+assert('重渲染使用稳定挂载 ref', registration.component().props.ref === element.props.ref)
 
 // ───────────────────────── 划词 → 浮标 ─────────────────────────
 const container = new FakeEl('div')
@@ -1264,7 +1270,7 @@ const selection = {
 windowStub.getSelection = () => selection
 documentStub.dispatch('mouseup', { target: body })
 await new Promise((r) => setTimeout(r, 20))
-const button = mount.children[0].children.find((c) => c.className === 'dsh-sel-btn')
+const button = floatingLayer.children.find((c) => c.className === 'dsh-sel-btn')
 assert('选中文字后浮标出现', !!button && button.style.display === 'inline-flex', button && `left=${button.style.left} top=${button.style.top}`)
 // 浮现动效：只在"隐藏 → 显示"那一次挂动效类；已可见时只平移；animationend 后自动摘掉
 {
@@ -1335,7 +1341,7 @@ assert('选中文字后浮标出现', !!button && button.style.display === 'inli
 // 引用（❝）的**离线**契约：浮标进了浮层、CSS 规则齐全（真实交互在宿主可达时另有一段）
 {
   const css = readFileSync(BUNDLE, 'utf8')
-  const quoteBtn = Array.from(walk(mount)).find((n) => String(n.className).indexOf('dsh-sel-quotebtn') >= 0)
+  const quoteBtn = Array.from(walk(floatingLayer)).find((n) => String(n.className).indexOf('dsh-sel-quotebtn') >= 0)
   assert('浮层里有「❝ 引用」浮标，且默认藏着', !!quoteBtn && quoteBtn.style.display === 'none' && textOf(quoteBtn).indexOf('引用') >= 0, quoteBtn ? textOf(quoteBtn) : '未找到')
   assert('CSS 契约：引用区默认收起、data-show 控制显隐', /\.dsh-sel-quotes\{display:none;flex-direction:column/.test(css) && /\.dsh-sel-quotes\[data-show="1"\]\{display:flex\}/.test(css), '')
   assert('CSS 契约：引用卡片三段（来源 / 摘要 / 删除）', /\.dsh-sel-quotechip-src\{/.test(css) && /\.dsh-sel-quotechip-text\{/.test(css) && /\.dsh-sel-quotechip-x\{/.test(css), '')
@@ -1361,12 +1367,12 @@ try {
 }
 
 button.dispatch('click', { preventDefault() {}, stopPropagation() {} })
-const panel = mount.children[0].children.find((c) => c.className === 'dsh-sel-panel')
+const panel = floatingLayer.children.find((c) => c.className === 'dsh-sel-panel')
 // 面板内的固定引用点（后续断言共用）
 const sections = Array.from(walk(panel)).filter((node) => node.className.indexOf('dsh-sel-sec') >= 0)
 const panelHead = Array.from(walk(panel)).find((node) => node.className === 'dsh-sel-head')
 const histBtn = Array.from(walk(panelHead)).find((n) => n.className.indexOf('dsh-sel-action') >= 0 && textOf(n).indexOf('最近') >= 0)
-const histList = mount.children[0].children.find((n) => n.className === 'dsh-sel-history')
+const histList = floatingLayer.children.find((n) => n.className === 'dsh-sel-history')
 assert('「最近聊过的」是独立浮层，不在消息滚动区里（B 方案）', !!histList && histList.parentNode.className === 'dsh-sel-layer' && !panel.contains(histList), histList ? histList.parentNode.className : '未找到')
 const detailCard = sections.find((node) => node.getAttribute('data-sec') === 'detail')
 const expandBtn = Array.from(walk(panel)).find((node) => node.className === 'dsh-sel-expand')
@@ -1378,7 +1384,7 @@ assert('弹窗显示选中文字', !!panel && textOf(panel).indexOf('the migrati
 // 指的是刚才解读的那段文字（解读要的文字与上下文在 mouseup 那刻就抓好了，见 openForSelection）
 assert('点「解读」后本文档选区被收掉', clearedSelections.count >= 1, `removeAllRanges 调用 ${clearedSelections.count} 次`)
 {
-  const quoteBtnNode = Array.from(walk(mount)).find((n) => String(n.className).indexOf('dsh-sel-quotebtn') >= 0)
+  const quoteBtnNode = Array.from(walk(floatingLayer)).find((n) => String(n.className).indexOf('dsh-sel-quotebtn') >= 0)
   assert(
     '点「解读」后引用浮标不出现（旧选区不该复活它）',
     !quoteBtnNode || quoteBtnNode.style.display === 'none',
@@ -5316,7 +5322,7 @@ assert('Esc/关闭后隐藏', panel.style.display === 'none')
 {
   // 也认 setAttribute('class') —— SVG 元素的 className 是只读对象，插件只能用 setAttribute
   const find = (cls) =>
-    Array.from(walk(mount)).find(
+    Array.from(walk(floatingLayer)).find(
       (n) => n.className === cls || (n.getAttribute && n.getAttribute('class') === cls),
     )
 
@@ -5434,7 +5440,7 @@ assert('Esc/关闭后隐藏', panel.style.display === 'none')
     threadDot ? 'cx=' + String(threadDot.getAttribute('cx')) + ' cy=' + String(threadDot.getAttribute('cy')) : 'none',
   )
 
-  const merged = Array.from(walk(mount)).filter((n) => n.className === 'dsh-sel-uline')
+  const merged = Array.from(walk(floatingLayer)).filter((n) => n.className === 'dsh-sel-uline')
   assert(
     '块级盒子被丢掉，两行各有一条下划线（不再整段只剩一条）',
     merged.length === 2,
@@ -6154,7 +6160,7 @@ for (const dispose of disposers.reverse()) {
   }
 }
 
-assert('清理后 DOM 归零', mount.children.length === 0 && body.children.indexOf(container) >= 0)
+assert('清理后自有根摘除，保留宿主 DOM', floatingLayer.parentNode === null && mount.children.length === 0 && body.children.indexOf(container) >= 0)
 assert('清理后划词桥自己建的预览 blob 被回收', bridgeOwnedBlob !== '' && !blobStore.has(bridgeOwnedBlob), bridgeOwnedBlob)
 assert('清理后钩子移除', windowStub.__dshSelectionExplain === undefined)
 console.log('\n=== 客户端集成测试结束 ===')

package/scripts/test-escape-focus.mjs

@@ -7,12 +7,14 @@ const start = source.indexOf('      var offKeyDown = listen(document,')
 const end = source.indexOf('\n\n      var offSettingsOpen', start)
 assert.ok(start >= 0 && end > start)
 const ask = {}, historyInput = {}, outside = {}, expandedChat = { closest: selector => selector.startsWith('[data-dsh-floating-chat]') ? {} : null }, compactChat = { closest: () => null }, nativeMenu = { closest: selector => selector.startsWith('[role=') ? {} : null }
-let handler, fullView = true, calls = [], activeWindow = null, chatExpanded = true
+let handler, fullView = true, calls = [], activeWindow = null, chatExpanded = true, hostModalOpen = false
 const context = vm.createContext({
   panelOpen: true, settingsOpen: false,
   panel: { contains: node => node === ask },
   historyList: { contains: node => node === historyInput },
-  document: { querySelector: selector => selector === '[data-dsh-full-view]' && fullView
+  document: { querySelector: selector => selector === '[role="dialog"][aria-modal="true"]'
+    ? hostModalOpen ? {} : null
+    : selector === '[data-dsh-full-view]' && fullView
     ? { getAttribute: () => activeWindow }
     : selector.startsWith('[data-dsh-floating-chat]') && chatExpanded ? {} : null },
   listen(target, type, callback, capture) { assert.equal(type, 'keydown'); assert.equal(capture, true); handler = callback },
@@ -27,7 +29,22 @@ function escape(target, extra = {}) {
   const event = { key: 'Escape', target, ...extra, preventDefault() { calls.push('prevent') }, stopPropagation() { calls.push('stop') } }
   handler(event)
 }
-function reset() { calls = []; activeWindow = null; chatExpanded = true; context.panelOpen = true; context.settingsOpen = false; context.settingsByKey = {}; context.captureRow.getAttribute = () => '0' }
+function reset() { calls = []; activeWindow = null; chatExpanded = true; hostModalOpen = false; context.panelOpen = true; context.settingsOpen = false; context.settingsByKey = {}; context.captureRow.getAttribute = () => '0' }
+for (const mode of [true, false]) {
+  for (const target of [ask, historyInput, outside, expandedChat]) {
+    reset(); fullView = mode; hostModalOpen = true; activeWindow = 'explanation'
+    escape(target)
+    assert.deepEqual(calls, [], '官方模态设置浮层优先消费 Esc，不受视图模式、焦点或最后操作窗口影响')
+    assert.equal(context.panelOpen, true)
+  }
+}
+reset(); fullView = true; hostModalOpen = true; context.settingsOpen = true; escape(ask)
+assert.deepEqual(calls, [], '官方设置打开时不关闭插件设置抽屉')
+assert.equal(context.settingsOpen, true)
+reset(); hostModalOpen = true; context.captureRow.getAttribute = () => '1'; escape(ask)
+assert.deepEqual(calls, [], '官方设置打开时不取消插件录音')
+hostModalOpen = false; escape(ask)
+assert.deepEqual(calls, ['prevent', 'stop', 'voice'], '官方设置退出后，下一次 Esc 恢复插件的内层退出顺序')
 reset(); activeWindow = 'chat'; escape(ask)
 assert.deepEqual(calls, [], '最后点击聊天后，即使键盘仍在解读输入框，也让聊天先退出')
 reset(); activeWindow = 'explanation'; escape(expandedChat)
@@ -63,4 +80,22 @@ for (const target of [ask, historyInput]) {
 }
 reset(); fullView = false; escape(outside)
 assert.equal(context.panelOpen, false, '普通分栏保留解读原来的全局 Esc 行为')
-console.log('PASS focused Esc: independent windows, IME, nested settings, voice, history and split-mode behavior')
+
+// 语音卡另有一个更早注册的 capture 监听，也必须给官方浮层让出 Esc。
+const panelHandler = handler
+const voiceStart = source.indexOf('      var offVoiceEscape = listen(document,')
+const voiceEnd = source.indexOf('\n      }, true)', voiceStart) + '\n      }, true)'.length
+assert.ok(voiceStart >= 0 && voiceEnd > voiceStart)
+context.vcardState = { open: true, suppress: false }
+context.closeVCard = () => { calls.push('vcard'); context.vcardState.open = false }
+new vm.Script(source.slice(voiceStart, voiceEnd)).runInContext(context)
+const voiceHandler = handler
+handler = panelHandler
+reset(); hostModalOpen = true
+voiceHandler({ key: 'Escape', preventDefault() { calls.push('prevent') }, stopPropagation() { calls.push('stop') } })
+assert.deepEqual(calls, [], '官方设置打开时，语音卡不抢先消费 Esc')
+assert.equal(context.vcardState.open, true)
+hostModalOpen = false
+voiceHandler({ key: 'Escape', preventDefault() { calls.push('prevent') }, stopPropagation() { calls.push('stop') } })
+assert.deepEqual(calls, ['prevent', 'stop', 'vcard'], '官方设置退出后，Esc 可以关闭语音卡')
+console.log('PASS focused Esc: host modals, independent windows, IME, nested settings, voice, history and split-mode behavior')

package/src/client/index.js

@@ -4,9 +4,9 @@
  * 交互：在页面任意位置选中文字 → 选区末端浮出「解读」按钮 → 点击弹出面板，
  * 面板流式显示两节：① 专业中英翻译 ② 这段文字在当前上下文中的含义详解。
  *
- * 挂载点走官方 shell.overlay 槽（帧级浮层：三栏之外、滚动容器之外、默认
- * click-through，条目自己 opt-in pointer-events）——因此 UI 不会挡住 App。
- * 浮标与面板用 position:fixed 定位到选区坐标，DOM 归 shell.overlay 条目所有。
+ * 官方 shell.overlay 槽管理挂载生命周期；界面由插件自己挂到 body 的独立根。
+ * 根层固定为 70，越过全屏工作面板，不改写宿主公共浮层。空白区域鼠标穿透。
+ * 浮标与面板继续用 position:fixed 定位到选区坐标。
  *
  * 本文件是 DSH 客户端 bundle 的源文件（ModuleLoader 懒加载 CJS 表格式）：
  * 顶层只注册工厂，真正的副作用（React 组件、DOM/CSS、监听）都在 factory 被
@@ -435,9 +435,10 @@ window.__ModuleLoader__.load({
       //   --sel-fill(-fg)  实心块：浮标按钮 / 发送键 / 结论条标签——块上文字另算一套，
       //                    否则青底配白字只有 3.6（不达标），浅色下换成深青 5.4、深色下反白 7.4
       // 变量挂在浮层容器上 → 浮标与面板共用；深浅由**面板实际底色**决定（data-theme）。
-      '.dsh-sel-layer{--sel-a1:#0d9488;--sel-a1-text:#0f766e;--sel-a2:#0d9488;--sel-a2-text:#0f766e;',
+      '.dsh-sel-layer{position:fixed;inset:0;z-index:70;pointer-events:none;--sel-a1:#0d9488;--sel-a1-text:#0f766e;--sel-a2:#0d9488;--sel-a2-text:#0f766e;',
       '--sel-fill:#0f766e;--sel-fill-fg:#ffffff;',
       '--sel-a2-soft:color-mix(in srgb,var(--sel-a2) 12%,transparent);--sel-a1-soft:color-mix(in srgb,var(--sel-a1) 10%,transparent)}',
+      '.dsh-sel-layer[data-full-view] .dsh-sel-pill{display:none!important}',
       '.dsh-sel-layer[data-theme=dark]{--sel-a1:#4ecdc4;--sel-a1-text:#6fe3d8;--sel-a2:#4ecdc4;--sel-a2-text:#6fe3d8;',
       '--sel-fill:#4ecdc4;--sel-fill-fg:#052b26;',
       '--sel-a2-soft:color-mix(in srgb,var(--sel-a2) 16%,transparent);--sel-a1-soft:color-mix(in srgb,var(--sel-a1) 16%,transparent)}',
@@ -2492,9 +2493,10 @@ window.__ModuleLoader__.load({
       styleEl.textContent = CSS
       document.head.appendChild(styleEl)
 
-      /** 浮层容器：挂在 shell.overlay 条目里，自身 click-through。 */
+      /** 自有浮层根：位于 body，公共父层的堆叠上下文不影响它。 */
       var layer = el('div', 'dsh-sel-layer')
       layer.style.pointerEvents = 'none'
+      layer.setAttribute('data-dsh-floating-owner', 'explanation')
 
       var button = el('button', 'dsh-sel-btn')
       button.type = 'button'
@@ -2646,7 +2648,7 @@ window.__ModuleLoader__.load({
       modelPill.appendChild(modelPillTier)
       modelPill.appendChild(el('span', 'dsh-sel-picker-caret', '▼'))
       var modelMenu = el('div', 'dsh-sel-pickermenu')
-      modelMenu.setAttribute('role', 'menu')
+      // role 随开合同步：DSH 按 [role="menu"] 判定弹层，不检查 CSS 可见性。
 
       // ── 录音行（与主会话 ui-voice-input 同一套结构）──
       //   [✕ 取消] [实时波形 / 状态文案] [■ 停止 或 行内动作] …… [↑ 发送（原位不动）]
@@ -3758,10 +3760,27 @@ window.__ModuleLoader__.load({
       layer.appendChild(historyList)
 
       /**
-       * 注册进官方 shell.overlay 槽（帧级浮层）。
-       * React 组件只负责把 layer 容器挂进浮层；浮标/面板由上面的命令式代码管理，
-       * React 不接管它们的子树（容器本身无 children，不会被 diff 清空）。
+       * 官方槽仅保留不可见的生命周期锚点；界面根由本插件挂到 body。
+       * 稳定 ref 避免 React 重渲染时摘挂根节点、丢失输入焦点。
        */
+      function syncFullViewLayer() {
+        var fullView = !!document.querySelector('[data-dsh-full-view]')
+        if (fullView !== layer.hasAttribute('data-full-view')) {
+          if (fullView) layer.setAttribute('data-full-view', '')
+          else layer.removeAttribute('data-full-view')
+        }
+      }
+      function mountFloatingLayer(node) {
+        if (node) {
+          if (layer.parentNode !== document.body) document.body.appendChild(layer)
+          syncFullViewLayer()
+        } else if (layer.parentNode) layer.parentNode.removeChild(layer)
+      }
+      var fullViewObserver = null
+      if (typeof MutationObserver === 'function') {
+        fullViewObserver = new MutationObserver(syncFullViewLayer)
+        fullViewObserver.observe(document.body, {subtree:true, childList:true, attributes:true, attributeFilter:['data-dsh-full-view']})
+      }
       /** 开窗后"还没聚焦过输入框"（见 focusComposerOnce）。 */
       var askFocusPending = false
       /** 调试：最后一次"没聚焦"卡在哪一步（-1 表示聚焦成功）。 */
@@ -3780,16 +3799,14 @@ window.__ModuleLoader__.load({
               },
             }, function SelectionExplainLayer() {
               return React.createElement('div', {
-                className: 'dsh-sel-mount',
-                style: { pointerEvents: 'none' },
-                ref: function (node) {
-                  if (node && layer.parentNode !== node) node.appendChild(layer)
-                },
+                className: 'dsh-sel-anchor',
+                style: { display: 'none', pointerEvents: 'none' },
+                ref: mountFloatingLayer,
               })
             })
           })
         } catch (error) {
-          // 槽注册失败不应把整页插件装载一起拖垮：降级为仅报错（面板挂在浮层外不可见）
+          // 槽注册失败仅报错，自有界面根保持未挂载，不影响其他插件。
           console.error('[dsh-selection-explain] shell.overlay 槽注册失败：', error)
         }
       } else {
@@ -9467,6 +9484,7 @@ window.__ModuleLoader__.load({
        */
       var offVoiceEscape = listen(document, 'keydown', function (event) {
         if (event.key !== 'Escape' || !vcardState.open || event.defaultPrevented) return
+        if (document.querySelector('[role="dialog"][aria-modal="true"]')) return
         event.preventDefault()
         event.stopPropagation()
         vcardState.suppress = true
@@ -9919,11 +9937,13 @@ window.__ModuleLoader__.load({
 
       function closeModelMenu() {
         modelMenu.setAttribute('data-open', '0')
+        modelMenu.removeAttribute('role')
         modelPill.setAttribute('aria-expanded', 'false')
       }
 
       function openModelMenu() {
         modelMenu.setAttribute('data-open', '1')
+        modelMenu.setAttribute('role', 'menu')
         modelPill.setAttribute('aria-expanded', 'true')
         renderModelMenu()
         loadModelCatalog(false).then(function () {
@@ -9945,7 +9965,7 @@ window.__ModuleLoader__.load({
         event.stopPropagation() // 菜单内部点击不要触发"点到外面"
       })
       var offModelKeys = listen(modelMenu, 'keydown', function (event) {
-        if (event.key === 'Escape') closeModelMenu()
+        if (event.key === 'Escape' && !document.querySelector('[role="dialog"][aria-modal="true"]')) closeModelMenu()
       })
 
       // —— 网页模式开关 ——
@@ -10123,6 +10143,9 @@ window.__ModuleLoader__.load({
 
       var offKeyDown = listen(document, 'keydown', function (event) {
         if (event.key !== 'Escape' || !panelOpen || event.defaultPrevented || event.isComposing || event.keyCode === 229) return
+        // 官方模态浮层的 Esc 在冒泡阶段处理；capture 不消费，先让官方设置等浮层退出。
+        // 插件面板和设置抽屉是非模态 dialog，不带 aria-modal，不会命中这里。
+        if (document.querySelector('[role="dialog"][aria-modal="true"]')) return
         // 完整视图记录最后点击/操作的小窗；不能只看可能停在另一窗的键盘焦点。
         var fullViewFrame = document.querySelector('[data-dsh-full-view]')
         if (fullViewFrame) {
@@ -12127,6 +12150,7 @@ window.__ModuleLoader__.load({
             }
             pillObserver = null
           }
+          if (fullViewObserver) fullViewObserver.disconnect()
           if (typeof offSlot === 'function') offSlot()
           // 划词桥：摘观察者与消息监听，并把我们自己建的预览 blob 全部回收
           if (bridgeScanId) clearTimeout(bridgeScanId)