From e24d9bf879a5c95f93576301e9321731952d7609 Mon Sep 17 00:00:00 2001
From: ZgblKylin <13114351+ZgblKylin@users.noreply.github.com>
Date: Sat, 22 Aug 2026 19:10:02 +0800
Subject: [PATCH] =?UTF-8?q?fix(sidebar):=20drop=20panel=20host=20below=20D?=
 =?UTF-8?q?SH=20cordis=20dynamic-plugin=20layer=20(z=2040=E2=86=9225)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ui-cordis CordisPanel is position:fixed at z-index 30; the unified
panel host at 40 made the bottom workbench cover the cordis inventory
and approval surfaces. Host now sits at 25 (above AppFrame overlay 20,
below cordis 30 and the 100+ float stack). Update skin contract docs
and add a mount e2e assertion for the layering band.
---
 AGENTS.md                                     |  4 +-
 docs/plans/2026-08-15-skin-compat-design.md   |  1 +
 ...9-sidebar-injection-unified-host-design.md |  5 ++-
 src/client/sidebar.module.css                 | 41 ++++++++++++-------
 tests/e2e/mount.e2e.ts                        |  9 ++++
 5 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f4ba2c8..e8868ab 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -606,7 +606,7 @@ interface OpenTabSeed {
 
 - **面板表面**：右/底面板背景 = `var(--dsw-alias-bg-layer-1)`（通用卡片表面）。**绝不消费 `--dsw-specific-sidebar-fill`**——那是宿主左侧导航列专属令牌，皮肤系统按左导航语义覆盖它（dsh-web-ui 皮肤把它做成半透明玻璃或主题色，Aqua 设成 `transparent`），面板消费它会失去填充或与标签令牌冲突。皮肤要整体换面板表面：覆写 `--dsw-alias-bg-layer-1` 即可（dsh-web-ui 10 款皮肤都已覆盖，无需任何额外工作）。
 - **终端/编辑器表面**：经 `effectiveTokenValue` 读取 `--dsw-alias-bg-base`——`transparent` 与 alpha < 0.9 的半透明玻璃值（dsh-web-ui 皮肤用 rgba 0.16–0.7）一律回退不透明底色，文字永不叠在皮肤背景画上滚动（issue #90）；≥ 0.9 的近不透明值（如皮肤作用域内 0.96 的瓷器玻璃）放行，皮肤仍能控制终端表面。
-- **根锚点**：宿主 div 带 `data-dsh-better-sidebar` 属性（append 到 `document.body`）。其内是**统一面板宿主层** `[data-dsh-panel-host]`（`position:fixed; inset:0; z-index:40; pointer-events:none`，v0.13.1+）：面板/开关簇在其内 **absolute** 定位（层 inset:0 即视口坐标），免疫桌面套壳中间层 transform 对 fixed 含块的劫持；页面级 transform（罕见）触发 `data-dsh-panel-host-degraded` 降级同步。皮肤若要做作用域覆盖（deep-whale 的做法），限定在 `[data-dsh-better-sidebar]` 内即可，避免全局改写影响宿主。
+- **根锚点**：宿主 div 带 `data-dsh-better-sidebar` 属性（append 到 `document.body`）。其内是**统一面板宿主层** `[data-dsh-panel-host]`（`position:fixed; inset:0; z-index:25; pointer-events:none`，v0.13.1+）：面板/开关簇在其内 **absolute** 定位（层 inset:0 即视口坐标），免疫桌面套壳中间层 transform 对 fixed 含块的劫持；页面级 transform（罕见）触发 `data-dsh-panel-host-degraded` 降级同步。皮肤若要做作用域覆盖（deep-whale 的做法），限定在 `[data-dsh-better-sidebar]` 内即可，避免全局改写影响宿主。
 - **布局变量**（写在 `<html>` 上，面板打开时有效）：`--dsh-sidebar-width` / `--dsh-sidebar-height`（面板几何；拖拽期间逐帧更新）。宿主推挤 = `#root` 的 `margin-right/width: calc(100% - var)`（v0.13.1+ 防桌面壳加性溢出）与 centerCol 的 `margin-bottom`；推挤锚点是**复合选择器**（同一元素双保险，禁止退回 `nth-child` 位置锚定）：`#root [data-dsh-frame] > [data-pane="conversation"]` **与** `#root :has(> [data-slot="conversation"])`（0.1.x 命名 / rc.8 时代命名，live 页面实测同元素；`drag-layout.e2e.ts` 断言两者同元素）。
 - **桌面信号与标题栏兼容**（v0.14.1+ 四选项模型，取代旧"win32 advanced 自动 32px"硬编码）：
   - 壳信号（只读报告，不自动触发任何修改）：URL `dsh-desktop-mode` / `dsh-desktop-platform`（DSH Desktop 壳注入；preload 另暴露 `__DSH_DESKTOP_FILE_PATH__`）；可选契约参数 `dsh-desktop-titlebar-inset`（壳声明自己预留的顶栏像素，0–120，clamp；`parseDesktopEnv().titlebarInset`）。
@@ -616,7 +616,7 @@ interface OpenTabSeed {
   - **用户空间 CSS**：预设 css（`<style data-dsh-preset-css>`）与自定义 css（`<style data-dsh-custom-css>`）经 `Sidebar.tsx` effect 注入到 `document.head` 末尾（后写胜出；覆盖 JS 内联变量需 `!important`），fiber 卸载/变更即移除。稳定寻址面（皮肤/预设/自定义 CSS 共用）：`[data-dsh-toggle-cluster]`、`[data-dsh-panel]`（右面板）、`[data-dsh-bottom-panel]`（底面板）。
   - **拖拽区退出**：插件交互 chrome（`.toggleCluster` / `.toggleButton` / `.tabBar`）统一 `-webkit-app-region: no-drag`——无边框壳的顶部拖拽带会吞点击（#103/#111），该属性在普通浏览器与无拖拽区壳中惰性无害。
   - `compatibility` 模式与无信号环境不避让。
-- **z-index**：面板宿主层 40、折叠按钮簇 45（角手柄在面板内层叠，z-index 2 仅面板内有效）——全部低于 DSH 浮层栈（100/1000+），任何浮层天然盖住侧边栏。
+- **z-index**：面板宿主层 25、折叠按钮簇 45（host 内部层叠；角手柄在面板内层叠，z-index 2 仅面板内有效）——全部低于 DSH 的 ui-cordis 动态插件面板（fixed，30，其清单/审批面不得被工作台遮挡）与 DSH 浮层栈（100/1000+），任何浮层天然盖住侧边栏。
 
 ### 8.2 注意事项
 
diff --git a/docs/plans/2026-08-15-skin-compat-design.md b/docs/plans/2026-08-15-skin-compat-design.md
index 237664c..20980dd 100644
--- a/docs/plans/2026-08-15-skin-compat-design.md
+++ b/docs/plans/2026-08-15-skin-compat-design.md
@@ -63,5 +63,6 @@ dsh-web-ui（`zhu1090093659/dsh-web-ui`）的皮肤机制：
 
 - **首版契约（已回退）**：初版围绕第三方皮肤插件设计了 `--dsh-sidebar-surface`/`--dsh-resize-strip-offset` 自有令牌（review 后已删）、panel 家族类名 kebab-case 改名（breaking）与 `data-bs-*` 语义钩子。确认主目标是 dsh-web-ui 皮肤中心后，按 KISS 全部回退：令牌驱动下这些都不需要，改名还引入无谓 breaking。最终契约 = 消费标准令牌 + 透明度阈值，无自有概念。
 - **角手柄 `z-index` 语义变化**：移入面板后 z-index 为面板内层叠（2，与拖条一致），对外绝对层级由面板（40）决定；两面板同开时手柄盒与底面板上沿无重叠（≥6px 间隙），行为不变。
+- **z-index 层级修正（2026-08-22）**：上文 "30–99 无任何 DSH 元素" 的假设不成立——DSH 的 ui-cordis 动态插件面板（`CordisPanel`，`position:fixed; z-index:30`，挂 `sidebar.footer.action` 槽）正落在该区间，且其清单/审批面会被 better-sidebar 的底部面板遮挡。修正：面板宿主层 40 → **25**（仍在 AppFrame overlayLayer 20 之上、ui-cordis 面板 30 与 DSH 浮层栈 100+ 之下），折叠按钮簇保持 host 内部 45（绝对层级随宿主 = 25）。
 - **拖拽禁用断言修正**：`transition: none` 的 computed 值为 `transition-property: none`（非 `all`），已按实测修正。
 - **面板默认表面色阶微调**：±8 RGB，未做像素级补偿（e2e 不依赖具体颜色）。
diff --git a/docs/plans/2026-08-19-sidebar-injection-unified-host-design.md b/docs/plans/2026-08-19-sidebar-injection-unified-host-design.md
index 28eafe6..24f4885 100644
--- a/docs/plans/2026-08-19-sidebar-injection-unified-host-design.md
+++ b/docs/plans/2026-08-19-sidebar-injection-unified-host-design.md
@@ -94,7 +94,7 @@
 ```
 document.body
 └─ div[data-dsh-better-sidebar]           ← 唯一锚点（属性不变，兼容既有契约/皮肤）
-   └─ div[data-dsh-panel-host]            ← 新增：position:fixed; inset:0; pointer-events:none; z-index:40
+   └─ div[data-dsh-panel-host]            ← 新增：position:fixed; inset:0; pointer-events:none; z-index:25（v0.15.x 起；初版为 40，2026-08-22 下调：ui-cordis 动态插件面板固定层 30，须在其上）
       ├─ 右侧面板（absolute; right:0; pointer-events:auto）
       └─ 底部面板（absolute; bottom:0; pointer-events:auto）
 ```
@@ -210,7 +210,7 @@ document.body
 
 **实施方式（2026-08-19 定稿）**：单分支 `feat/injection-unified-host`、按步骤顺序提交（每步 CI 绿）；原 PR1/PR2 拆分为内部步骤，合并为**一个 PR** 交付（改动彼此耦合，且路线 B 关闭后无外部依赖）。各步骤：
 
-1. **挂载层**（`src/client/index.tsx`、`src/client/Sidebar.tsx`、`src/client/sidebar.module.css`）：`Sidebar` 渲染根包 `data-dsh-panel-host`（`position:fixed; inset:0; pointer-events:none; z-index:40`）；`.panel/.toggleCluster/.bottomPanel` 由 fixed 改 absolute（层 inset:0 即视口坐标）+ `pointer-events:auto`；挂载后一次性几何自检（偏差 >8px → `data-dsh-panel-host-degraded` + rAF 视口同步 + warn 一次）；`MutationObserver`（body childList）守卫锚点被清空时重挂。✅ 已实施（commit 9a4c160）
+1. **挂载层**（`src/client/index.tsx`、`src/client/Sidebar.tsx`、`src/client/sidebar.module.css`）：`Sidebar` 渲染根包 `data-dsh-panel-host`（`position:fixed; inset:0; pointer-events:none; z-index:25`，初版 40，2026-08-22 起 25）；`.panel/.toggleCluster/.bottomPanel` 由 fixed 改 absolute（层 inset:0 即视口坐标）+ `pointer-events:auto`；挂载后一次性几何自检（偏差 >8px → `data-dsh-panel-host-degraded` + rAF 视口同步 + warn 一次）；`MutationObserver`（body childList）守卫锚点被清空时重挂。✅ 已实施（commit 9a4c160）
 2. **几何层**（`Sidebar.tsx`、`sidebar.module.css`）：`writeGeometry` 统一拖拽/打开态两条推挤写路径；面板 `contain: layout style`；拖拽期（`body[data-dsh-sidebar-dragging]`）`will-change: transform`。✅ 已实施（commit 553e650）
 3. **chunk 缓存**（`chunk-loader.ts`、`index.tsx`）：`revalidateChunksOnReactivate()`——激活时 HEAD 每个已加载 chunk 对比 ETag，未变保留已解析 exports（跳过重注入/重执行），变更/不可达 fail-open 重取；测试夹具与孤儿缓存不跨激活存活。✅ 已实施（commit 0264625）
 4. **锚点与防溢出**（`layout.css`）：底部推挤锚点 `nth-child(2)` → `#root [data-dsh-frame] > [data-pane="conversation"]`（§3.4 实证）；`#root` 加 `width: calc(100% - var(...))` 与 margin 锁步过渡（实测 1140+300=1440 无溢出；#226 桌面溢出根因吸收）。✅ 已实施（commit 9c9515d）
@@ -258,3 +258,4 @@ document.body
   - 测试环境为 Node + 手写 shim（非 jsdom）：`browser-globals.ts` 补 `location`；desktop-env 剥除 `location.search` 前导 `?`（真实 bug，顺带修复）。
   - 本地 Node 24 跑 `test:mount` 需 `node --expose-internals` 启动 dsh CLI（HMR 服务要求，CI Node 22 无此问题）——本地用 DSH_CMD 包装，不改仓库脚本。
   - **CR #232 修复（2026-08-19）**：① 降级同步改为按**未修正几何**判定（跟踪自身补偿量，祖先 transform 消失才退出循环）；② chunk 重验证成为 `loadChunk` 屏障（重验证挂起期间不提供缓存，杜绝 HMR 竞态陈旧 exports）；③ 键盘 inset 公式补 `visualViewport.offsetTop` 并监听 `scroll`。
+  - **z-index 40→25（2026-08-22）**：设计初稿的"30–99 无任何 DSH 元素"（源自 #52 修复记录）低估了官方 ui-cordis 的动态插件面板（fixed z-index 30，挂 `sidebar.footer.action` 槽）——better-sidebar 底部面板曾盖住其清单/审批面。下调宿主层至 25（AppFrame overlayLayer 20 之上、ui-cordis 30 与 DSH 浮层栈 100+ 之下），折叠按钮簇 45 保留为 host 内部层叠；`AGENTS.md` §8 与 `2026-08-15-skin-compat-design.md` 已同步。
diff --git a/src/client/sidebar.module.css b/src/client/sidebar.module.css
index f648d4c..18f8d71 100644
--- a/src/client/sidebar.module.css
+++ b/src/client/sidebar.module.css
@@ -24,15 +24,18 @@
    containing block for every panel element. Panels are ABSOLUTE within it
    (not fixed), so a desktop shell's intermediate wrapper transform can
    never hijack their containing block — the host itself is the only fixed
-   element, appended directly to document.body. The layer sits at z-index 40
-   (below the app's overlay stack at 100+); each panel re-enables pointer
+   element, appended directly to document.body. The layer sits at z-index 25:
+   above the app's shell overlay (AppFrame overlayLayer, 20) and in-flow
+   content, below DSH's ui-cordis dynamic-plugin panel (fixed, 30 — the
+   inventory/surfacing surface must never be hidden behind the workbench),
+   and below the app's overlay stack at 100+; each panel re-enables pointer
    events on itself. Degraded mode ([data-dsh-panel-host-degraded]) covers
    the rare shell that transforms <html>/<body> itself: the host becomes
    absolute and the mount self-check pins it to the viewport every frame. */
 :global([data-dsh-panel-host]) {
   position: fixed;
   inset: 0;
-  z-index: 40;
+  z-index: 25;
   pointer-events: none;
 }
 
@@ -46,11 +49,13 @@
    controls side by side (bottom panel's glyph LEFT of the right panel's).
    Always pinned to the viewport corner — inside the right panel's top-right
    while it is open, sitting flush in the 34px tab strip (28px buttons at
-   top: 3) whose right end it really squeezes. z-index 45: above the panels
-   (40) but below the app's overlay stack (menus/tooltips/modals sit at
-   100+), so a cordis approval popup is never hidden behind the workbench
-   (issue #52). Absolute within the panel host (the host's inset: 0 makes
-   viewport coordinates identical). */
+   top: 3) whose right end it really squeezes. Host-internal z-index 45
+   (above the panels' 40); the host's global layer is z-index 25, so the
+   whole cluster stays below DSH's ui-cordis dynamic-plugin panel (30) and
+   the app's overlay stack (menus/tooltips/modals sit at 100+), so a cordis
+   approval popup is never hidden behind the workbench (issue #52). Absolute
+   within the panel host (the host's inset: 0 makes viewport coordinates
+   identical). */
 .toggleCluster {
   position: absolute;
   /* env() resolves to 0 on devices without a top inset (desktops). */
@@ -108,10 +113,14 @@
   /* Full height: the bottom panel squeezes only the center column, so the
      right panel never gives up any vertical position. */
   bottom: 0;
-  /* z-index 40: above the app's in-flow content, below the app's overlay
-     stack (100+), so menus/tooltips/modals always win over the panels
-     (issue #52). The toggle cluster (45) sits above it; the corner handle
-     is a child and stacks within the panel. */
+  /* Host-internal z-index 40 (sibling of the bottom panel's 40; the two
+     never overlap — the bottom panel's right edge is this panel's left
+     edge — and both sit below the toggle cluster's 45). The absolute
+     global layer comes from the host ([data-dsh-panel-host], 25) — the
+     whole stack stays above the app's in-flow content and below DSH's
+     ui-cordis dynamic-plugin panel (30) and the app's overlay stack (100+),
+     so menus/tooltips/modals always win over the panels (issue #52). The
+     corner handle is a child and stacks within the panel. */
   z-index: 40;
   display: flex;
   flex-direction: column;
@@ -178,9 +187,11 @@
    column only (the Sidebar shell writes left/right inline: from the app's
    own left sidebar to the right panel's left edge) — the sidebars never
    give up any position. Same surface as the right panel, with a top
-   hairline instead of the left one. z-index 40 mirrors the right panel
-   (issue #52: below the app's overlay stack so popups win over the
-   workbench). */
+   hairline instead of the left one. Host-internal z-index 40 mirrors the
+   right panel; the absolute global layer comes from the host (25), below
+   DSH's ui-cordis dynamic-plugin panel (30) so the cordis inventory
+   surface floats above the workbench, and below the app's overlay stack
+   (100+) so popups win over the workbench (issue #52). */
 .bottomPanel {
   position: absolute;
   bottom: 0;
diff --git a/tests/e2e/mount.e2e.ts b/tests/e2e/mount.e2e.ts
index bc44df1..8bf81e8 100644
--- a/tests/e2e/mount.e2e.ts
+++ b/tests/e2e/mount.e2e.ts
@@ -143,6 +143,15 @@ test('plugin mounts into the DSH shell and survives a built-in tab sweep', async
   // The unified panel host: the fixed containing block every panel lives in
   // (data-dsh-panel-host). Its presence is part of the injection contract.
   await expect(page.locator('[data-dsh-panel-host]')).toBeAttached({ timeout: 90_000 })
+  // The host's global z-index is part of the layering contract: it must
+  // sit above the AppFrame overlay layer (20) and below DSH's ui-cordis
+  // dynamic-plugin panel (fixed, 30) so that surface is never hidden behind
+  // the workbench, and below the DSH float stack (100+).
+  const hostZ = await page.locator('[data-dsh-panel-host]').evaluate(
+    (el) => Number.parseFloat(getComputedStyle(el).zIndex),
+  )
+  expect(hostZ).toBeGreaterThan(20)
+  expect(hostZ).toBeLessThan(30)
 
   // A keyless boot stacks onboarding takeovers that mask the whole shell: a
   // versioned welcome notice ("Continue", persists its acknowledgement to