fix(ui): compact context menus + viewport-clamped submenu flip

减重：全部右键菜单（FileTree 行菜单 / TabBar tab 菜单 / GitLens 文件与
历史菜单 / FreeWindow 标题菜单）与「+」菜单切到宿主 Menu 原语的 compact
密度（26px 行高 / 12px 字 / 164px 卡片），图标随槽位 16→14，「打开方式」
子菜单图钉 20→16，还原工具型右键菜单的趁手感。

越界：宿主子菜单纯 CSS 定位（从父行向上、向右生长）不受视口钳制——树顶
部右键时「打开方式 ▸」子菜单伸出视口上沿，窄面板（280–400px）时伸出右
沿。新增 menu-flip.ts：菜单打开期间在 <body> 发布 data-dsh-sidebar-submenu
="down|left" 方向 token（y < vh/2 → down；x + 400 > vw → left），layout.css
据此翻转子菜单生长方向与 ::before 悬停桥；属性存续期即作用域，宿主自有
菜单不受影响。刻意不做 max-height 滚动钳制——overflow 裁剪会切断悬停桥。

测试：menu-flip.spec.tsx（token 纯函数 + hook 生命周期 + CSS 契约跨文件
一致性）；tab-bar / file-tree 两个 spec 追加翻转向量断言；mount.e2e 追加
compact 行高（≤30px）布局级证据。设计偏差记录同步至
docs/plans/2026-08-22-open-with-menu-design.md。

tests/e2e/mount.e2e.ts

@@ -281,6 +281,13 @@ test('plugin mounts into the DSH shell and survives a built-in tab sweep', async
     await newTabButton.click()
     const item = page.getByRole('menuitem', { name: title }).first()
     await expect(item, `built-in tab "${title}" is not offered by the + menu — descriptor removed or its label changed`).toHaveCount(1)
+    if (title === BUILTIN_TABS[0]) {
+      // Layout-level evidence for the compact density: rows render ~26px
+      // tall (the default density would be 40px). Guard loose at ≤30px so
+      // font/zoom differences across runners cannot flake it.
+      const rowHeight = await item.evaluate(el => el.getBoundingClientRect().height)
+      expect(rowHeight, '+ menu rows must render at the compact density (≤30px)').toBeLessThanOrEqual(30)
+    }
     await item.click()
     // Let the activation commit (including any lazy-chunk fetch) before the
     // crash assertions run.

tests/file-tree-open-with.spec.tsx

@@ -204,3 +204,45 @@ describe('FileTree open-with menu', () => {
     expect(items.some(item => item.getAttribute('aria-haspopup') === 'menu')).toBe(false)
   })
 })
+
+describe('FileTree open-with menu flip geometry (submenu clamping)', () => {
+  const ATTR = 'data-dsh-sidebar-submenu'
+
+  let harness: Harness
+  afterEach(() => {
+    harness.unmount()
+    document.body.innerHTML = ''
+    document.body.removeAttribute(ATTR)
+  })
+
+  it('publishes "down" for a top-of-tree opening and clears on selection', async () => {
+    harness = await mountTree()
+    // openMenu() right-clicks at (20, 30) — the upper half, plenty of right
+    // room in jsdom's default viewport.
+    openMenu(harness.container)
+    expect(document.body.getAttribute(ATTR)).toBe('down')
+    const parent = [...document.querySelectorAll<HTMLElement>('[role="menuitem"]')]
+      .find(item => item.getAttribute('aria-haspopup') === 'menu')
+    act(() => { parent!.click() })
+    const zedRow = [...document.querySelectorAll<HTMLElement>('[role="menu"] [role="menu"] [role="menuitem"]')]
+      .find(item => item.textContent?.trim() === 'Zed')
+    act(() => { zedRow!.click() })
+    expect(document.querySelector('[role="menuitem"]')).toBeNull()
+    expect(document.body.hasAttribute(ATTR)).toBe(false)
+  })
+
+  it('adds "left" when the cursor sits within the right-hand submenu room', async () => {
+    harness = await mountTree()
+    const nearRight = new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: window.innerWidth - 10, clientY: 30 })
+    act(() => { fileRow(harness.container).dispatchEvent(nearRight) })
+    expect(document.body.getAttribute(ATTR)).toBe('down left')
+  })
+
+  it('clears the attribute on unmount with the menu still open', async () => {
+    harness = await mountTree()
+    openMenu(harness.container)
+    expect(document.body.getAttribute(ATTR)).toBe('down')
+    harness.unmount()
+    expect(document.body.hasAttribute(ATTR)).toBe(false)
+  })
+})

tests/menu-flip.spec.tsx

@@ -0,0 +1,110 @@
+/**
+ * The context-menu submenu flip geometry: the pure token computation behind
+ * the body attribute layout.css consumes (see src/client/menu-flip.ts for
+ * the contract) plus the attribute lifecycle of the hook itself.
+ */
+// @vitest-environment jsdom
+import { createElement, useState } from 'react'
+import { readFileSync } from 'node:fs'
+import { act } from 'react-dom/test-utils'
+import { describe, expect, it } from 'vitest'
+import { renderRoot, setupReactAct } from './test-utils.ts'
+import { SUBMENU_FLIP_ATTR, submenuFlipTokens, useSubmenuFlip } from '../src/client/menu-flip.ts'
+
+setupReactAct()
+
+describe('layout.css contract', () => {
+  it('consumes the exact attribute name menu-flip.ts publishes', () => {
+    // The two halves of the flip mechanism can drift silently: renaming the
+    // attribute here would leave layout.css matching nothing (submenus revert
+    // to overflowing) with every test still green. Tie them together. Specs
+    // run from the repo root (chunk-artifact.spec.ts reads lib/ the same way).
+    const css = readFileSync('src/client/layout.css', 'utf8')
+    expect(css).toContain(`body[${SUBMENU_FLIP_ATTR}~="down"] div[role="menu"] div[role="menu"]`)
+    expect(css).toContain(`body[${SUBMENU_FLIP_ATTR}~="left"] div[role="menu"] div[role="menu"]`)
+    expect(css).toContain(`body[${SUBMENU_FLIP_ATTR}~="left"] div[role="menu"] div[role="menu"]::before`)
+  })
+})
+
+describe('submenuFlipTokens', () => {
+  // Default geometry (1024x768): the panel is docked right, so the
+  // interesting split is the right-hand 400px strip and the vertical half.
+  it('flips down for a cursor in the upper half, keeps primitive defaults below', () => {
+    expect(submenuFlipTokens(500, 20, 1024, 768)).toBe('down')
+    expect(submenuFlipTokens(500, 700, 1024, 768)).toBe('')
+  })
+
+  it('flips left when the right-hand room cannot fit card + submenu', () => {
+    // 700 + 400 > 1024 → left; the cursor is low, so no down token.
+    expect(submenuFlipTokens(700, 700, 1024, 768)).toBe('left')
+    // Both tokens compose for a top-right opening.
+    expect(submenuFlipTokens(700, 20, 1024, 768)).toBe('down left')
+  })
+
+  it('uses the exact boundary inclusively (midpoint and width-minus-room still flip)', () => {
+    expect(submenuFlipTokens(500, 384, 1024, 768)).toBe('')
+    expect(submenuFlipTokens(500, 383, 1024, 768)).toBe('down')
+    expect(submenuFlipTokens(624, 700, 1024, 768)).toBe('')
+    expect(submenuFlipTokens(625, 700, 1024, 768)).toBe('left')
+  })
+
+  it('flips left throughout a narrow panel viewport (PANEL_MIN 280)', () => {
+    // A 600px window: any cursor past x=200 flips; the left strip cannot
+    // fit a right-growing submenu beside the 218px card either way.
+    expect(submenuFlipTokens(300, 100, 600, 800)).toBe('down left')
+    expect(submenuFlipTokens(500, 700, 600, 800)).toBe('left')
+  })
+})
+
+describe('useSubmenuFlip', () => {
+  const ATTR = 'data-dsh-sidebar-submenu'
+
+  /** Mount a probe whose menu state the spec drives via the returned setter. */
+  function mountFlipProbe(initial: { x: number; y: number } | null): { setMenu: (next: { x: number; y: number } | null) => void, unmount: () => void } {
+    let applyMenu: (next: { x: number; y: number } | null) => void = () => {}
+    function Probe(): React.ReactElement {
+      const [menu, setMenu] = useState<{ x: number; y: number } | null>(initial)
+      applyMenu = setMenu
+      useSubmenuFlip(menu)
+      return <div />
+    }
+    const rendered = renderRoot(createElement(Probe))
+    return {
+      setMenu: (next) => { act(() => { applyMenu(next) }) },
+      unmount: rendered.unmount,
+    }
+  }
+
+  it('publishes tokens while the menu is open and clears on close', () => {
+    const probe = mountFlipProbe({ x: 700, y: 20 })
+    try {
+      expect(document.body.getAttribute(ATTR)).toBe('down left')
+      probe.setMenu(null)
+      expect(document.body.hasAttribute(ATTR)).toBe(false)
+    } finally {
+      probe.unmount()
+    }
+  })
+
+  it('tracks the position across consecutive openings', () => {
+    const probe = mountFlipProbe({ x: 100, y: 20 })
+    try {
+      expect(document.body.getAttribute(ATTR)).toBe('down')
+      // Still open, now lower-left: the attribute stays (menu lifetime) but
+      // carries no token, so the primitive's own geometry applies.
+      probe.setMenu({ x: 100, y: 700 })
+      expect(document.body.getAttribute(ATTR)).toBe('')
+      probe.setMenu({ x: 700, y: 700 })
+      expect(document.body.getAttribute(ATTR)).toBe('left')
+    } finally {
+      probe.unmount()
+    }
+  })
+
+  it('clears the attribute when the owner unmounts with the menu still open', () => {
+    const probe = mountFlipProbe({ x: 100, y: 20 })
+    expect(document.body.getAttribute(ATTR)).toBe('down')
+    probe.unmount()
+    expect(document.body.hasAttribute(ATTR)).toBe(false)
+  })
+})

tests/tab-bar-context-menu.spec.tsx

@@ -309,3 +309,61 @@ describe('TabBar pin submenu (v0.17.0)', () => {
     }
   })
 })
+
+describe('TabBar context menu flip geometry (submenu clamping)', () => {
+  const ATTR = 'data-dsh-sidebar-submenu'
+
+  /** jsdom's default viewport (what the hook reads via window.innerWidth/Height). */
+  const VW = window.innerWidth
+  const VH = window.innerHeight
+
+  it('publishes "down" while the menu is open and clears it on selection', () => {
+    stubZh()
+    const { tabEls, onClose, unmount } = mountBar(fourTabs())
+    try {
+      // rightClick() dispatches at clientY 40 — the top strip, upper half.
+      act(() => { rightClick(tabEls[1]!) })
+      expect(document.body.getAttribute(ATTR)).toBe('down')
+      act(() => { menuItems()[1]!.click() })
+      expect(onClose).toHaveBeenCalledWith('t2')
+      expect(document.body.hasAttribute(ATTR)).toBe(false)
+    } finally {
+      unmount()
+    }
+  })
+
+  it('flips left when the cursor sits within the right-hand submenu room', () => {
+    stubZh()
+    const { tabEls, unmount } = mountBar(fourTabs())
+    try {
+      const nearRight = new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: VW - 10, clientY: 40 })
+      act(() => { tabEls[1]!.dispatchEvent(nearRight) })
+      expect(document.body.getAttribute(ATTR)).toBe('down left')
+    } finally {
+      unmount()
+    }
+  })
+
+  it('keeps the primitive defaults (empty tokens) for a lower-half opening', () => {
+    stubZh()
+    const { tabEls, unmount } = mountBar(fourTabs())
+    try {
+      const lowLeft = new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: 120, clientY: VH - 40 })
+      act(() => { tabEls[1]!.dispatchEvent(lowLeft) })
+      // Attribute present but empty: layout.css matches no token, so the
+      // host primitive's own up/right geometry applies.
+      expect(document.body.getAttribute(ATTR)).toBe('')
+    } finally {
+      unmount()
+    }
+  })
+
+  it('clears the attribute on unmount with the menu still open', () => {
+    stubZh()
+    const { tabEls, unmount } = mountBar(fourTabs())
+    act(() => { rightClick(tabEls[1]!) })
+    expect(document.body.getAttribute(ATTR)).toBe('down')
+    unmount()
+    expect(document.body.hasAttribute(ATTR)).toBe(false)
+  })
+})