fix: restore consistent controls, usable overlays and narrow layouts

Resolve 15 shared-control, overlay and responsive-layout issues plus the MCP editor being hidden behind settings. Restore theme contrast, danger and disabled states, visible keyboard focus, and consistent Continue fields. Keep the workbar add button reachable and model protocol values readable in narrow containers.

Make nested MCP and image dialogs usable above their parents with focus restoration, keep project Escape handling within the active modal, release native browser views for overlapping help, and restore keyboard access and Escape in sandboxed HTML previews without relaxing sandbox permissions. Add unit and real Electron regression coverage and update design and validation documentation.

Release note: 修复深浅主题下控件边框、危险操作、禁用状态和键盘焦点显示不一致的问题。MCP 编辑器与图片预览可在父弹窗上正常操作，HTML 全屏预览支持键盘进入和 Escape 返回；窄工作栏的添加按钮保持可用，模型连接协议文字完整可读。

Validation: the full suite recorded 5309 passed, 3 failed and 83 skipped. The ProjectSwitcher initial-focus regression was then fixed, and App, ProjectSwitcher and overlay Electron tests passed all 331 cases. The other two HeartbeatCenter failures were reproduced on isolated HEAD 11facf0 and remain pre-existing. Typecheck and lint passed after the fix; staged whitespace checks passed. The full suite was not rerun after the focused fix.

Limits: Electron evidence is from Windows development runs, with fixtures for unrelated services and native occlusion throttling disabled in some drivers. No production build, packaging, macOS/Linux, remote Agent host or external MCP connection validation; skipped tests and the documented scaling and native-select coverage gaps remain.

src/main/ipc.test.ts

@@ -102,7 +102,7 @@ describe('terminal IPC boundary', () => {
   })
 
   it('validates terminal requests and routes them through the trusted renderer owner', async () => {
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       id: 73,
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
@@ -1065,7 +1065,7 @@ describe('registerIpcHandlers update source routing', () => {
   })
 
   it('uses the persisted source for checks and the download page', async () => {
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       isDestroyed: vi.fn(() => false),
@@ -1172,7 +1172,7 @@ describe('registerIpcHandlers model download source routing', () => {
   })
 
   it('uses the persisted source and rejects stale renderer requests', async () => {
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       isDestroyed: vi.fn(() => false),
@@ -1421,7 +1421,7 @@ describe('registerIpcHandlers DSH runtime extensions', () => {
   })
 
   it('validates extension actions, reloads the Runtime, and trusts only the renderer', async () => {
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       isDestroyed: vi.fn(() => false),
@@ -1568,7 +1568,7 @@ describe('registerIpcHandlers SSH hosts', () => {
   })
 
   it('validates narrow host requests and restricts them to the trusted renderer', async () => {
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       isDestroyed: vi.fn(() => false),
@@ -2302,7 +2302,7 @@ describe('registerIpcHandlers SSH hosts', () => {
       setProjectArchived: vi.fn(),
       deleteProject: vi.fn()
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       isDestroyed: vi.fn(() => false),
@@ -2667,7 +2667,7 @@ describe('registerIpcHandlers lifecycle tracking', () => {
     const workspace = await mkdtemp(
       join(tmpdir(), 'goodbuddy-ipc-settings-')
     )
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -2879,7 +2879,7 @@ describe('registerIpcHandlers lifecycle tracking', () => {
       .mockRejectedValueOnce(activationError)
       .mockRejectedValueOnce(rollbackError)
     const repairs = vi.fn()
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -3041,7 +3041,7 @@ describe('registerIpcHandlers lifecycle tracking', () => {
     })
     const repairs = vi.fn(() => [])
     const reportRepairs = vi.fn()
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -3179,7 +3179,7 @@ describe('registerIpcHandlers knowledge snapshot ontology', () => {
         tasks: []
       }))
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -3267,7 +3267,7 @@ describe('registerIpcHandlers knowledge embedding index', () => {
         knowledgeEmbeddingApiKeyConfigured: false
       }))
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -3361,7 +3361,7 @@ describe('registerIpcHandlers knowledge task actions', () => {
       cancelTask: vi.fn(async () => true),
       retryTask: vi.fn(async () => undefined)
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -3432,7 +3432,7 @@ describe('registerIpcHandlers model ZIP dialogs', () => {
   })
 
   it('imports and exports speech and OCR ZIPs through trusted dialogs', async () => {
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -3665,7 +3665,7 @@ describe('registerIpcHandlers document parsing', () => {
       listPendingConversationQueueIds: vi.fn(() => []),
       createInlineArtifact
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -3811,7 +3811,7 @@ describe('registerIpcHandlers connection tests', () => {
       dispose: vi.fn(async () => undefined)
     }
     const getResolvedSettings = vi.fn(async () => resolvedSettings)
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -3934,7 +3934,7 @@ describe('registerIpcHandlers connection tests', () => {
       getStatus: vi.fn(),
       dispose: vi.fn(async () => undefined)
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -4029,7 +4029,7 @@ describe('registerIpcHandlers Runtime config actions', () => {
         continueConfigPath: configPath
       }
     }))
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -4160,7 +4160,7 @@ describe('registerIpcHandlers window controls', () => {
   it('restricts custom chrome controls to the trusted main window', async () => {
     let maximized = false
     const listeners = new Map<string, () => void>()
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()
@@ -4259,7 +4259,7 @@ describe('registerIpcHandlers workspace files', () => {
       listPendingConversationQueueIds: vi.fn(() => []),
       getProject: vi.fn(() => ({ id: projectId, rootPath }))
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html')
     }
@@ -4348,7 +4348,7 @@ describe('registerIpcHandlers workspace files', () => {
         updatedAt: '2026-08-01T00:00:00.000Z'
       }))
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html')
     }
@@ -4424,7 +4424,7 @@ describe('registerIpcHandlers token usage', () => {
       listPendingConversationQueueIds: vi.fn(() => []),
       getExecutionStatsAsync: vi.fn(async () => summary)
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'), send: vi.fn()
     }
@@ -4470,7 +4470,7 @@ describe('registerIpcHandlers token usage', () => {
       listPendingConversationQueueIds: vi.fn(() => []),
       getTokenUsageSummary: vi.fn(() => summary)
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: {
         url: 'file:///goodbuddy/index.html'
       },
@@ -4575,7 +4575,7 @@ describe('registerIpcHandlers local conversation persistence', () => {
       clear: vi.fn(),
       remove: vi.fn()
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: {
         url: 'file:///goodbuddy/index.html'
       },
@@ -4709,7 +4709,7 @@ describe('registerIpcHandlers local conversation persistence', () => {
       listConversationQueueItems: vi.fn(() => []),
       listPendingConversationQueueIds: vi.fn(() => [])
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: {
         url: 'file:///goodbuddy/index.html'
       },
@@ -4829,7 +4829,7 @@ describe('registerIpcHandlers Runtime customization', () => {
         detail: 'OpenCode manages native context'
       }
     }
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       isDestroyed: vi.fn(() => false),
@@ -5321,7 +5321,7 @@ describe('registerIpcHandlers agent terminal state', () => {
         rootPath: 'C:\\ProjectWorkspace'
       }))
     }
-    const webContents = {
+    const webContents = { on: vi.fn(),
       id: 9,
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
@@ -12728,7 +12728,7 @@ describe('registerIpcHandlers Magic Notes analysis', () => {
     runtimeFactoryMocks.createDefaultModelRuntime.mockReturnValue(
       analysisRuntime
     )
-    const webContents = {
+    const webContents = { on: vi.fn(), removeListener: vi.fn(),
       mainFrame: { url: 'file:///goodbuddy/index.html' },
       getURL: vi.fn(() => 'file:///goodbuddy/index.html'),
       send: vi.fn()

src/main/ipc.ts

@@ -3257,7 +3257,7 @@ export function registerIpcHandlers(
     false
   )
 
-  registerWindowIpcHandlers(registerHandler, window)
+  const disposeWindowIpc = registerWindowIpcHandlers(registerHandler, window)
 
   registerHandler(ipcChannels.appClearLocalData, (event) => {
     assertTrustedSender(event, window)
@@ -7374,6 +7374,7 @@ export function registerIpcHandlers(
   registerKnowledgeIpcHandlers(registerHandler, window, knowledgeService, settingsStore)
 
   return async () => {
+    disposeWindowIpc()
     shuttingDown = true
     if (nativeClientCoordinator) window.webContents.removeListener('destroyed', closeNativeClients)
     await nativeClientCoordinator?.closeOwner(nativeClientOwnerId)

src/main/magic-notes/canvas-ipc.integration.test.ts

@@ -65,6 +65,7 @@ describe('production preload -> registered IPC -> SQLite canvas persistence', ()
   let api: DesktopApi['magicNotes']
   let applicationSettings: ApplicationSettingsStore
   const webContents = { id: 91, mainFrame: { url: 'file:///canvas-test/index.html' },
+    on: vi.fn(), removeListener: vi.fn(),
     getURL: () => 'file:///canvas-test/index.html', isDestroyed: () => false, send: vi.fn() }
   const window = { webContents, isDestroyed: () => false, isMaximized: () => false,
     on: vi.fn(), removeListener: vi.fn() }

src/main/window-ipc.test.ts

@@ -0,0 +1,40 @@
+import { EventEmitter } from 'node:events'
+import type { BrowserWindow, ipcMain } from 'electron'
+import { expect, it, vi } from 'vitest'
+import { ipcChannels } from '../shared/ipc-channels'
+import { registerWindowIpcHandlers } from './window-ipc'
+
+vi.mock('electron', () => ({ clipboard: {} }))
+vi.mock('./window', () => ({ showWindow: vi.fn() }))
+
+it('relays only direct srcdoc Escape keydowns and removes the listener on disposal', () => {
+  const mainFrame = { url: 'file:///app/index.html', parent: null }
+  const contents = Object.assign(new EventEmitter(), {
+    mainFrame, focusedFrame: mainFrame as { url: string; parent: unknown } | null, send: vi.fn()
+  })
+  let destroyed = false
+  const window = { get webContents() {
+    if (destroyed) throw new Error('Object has been destroyed')
+    return contents
+  } }
+  const dispose = registerWindowIpcHandlers(vi.fn() as typeof ipcMain.handle, window as unknown as BrowserWindow)
+  const input = (key = 'Escape', type = 'keyDown'): void => { contents.emit('before-input-event', {}, { key, type }) }
+  input()
+  contents.focusedFrame = null
+  input()
+  contents.focusedFrame = { url: 'https://example.com', parent: mainFrame }
+  input()
+  contents.focusedFrame = { url: 'about:srcdoc', parent: {} }
+  input()
+  contents.focusedFrame = { url: 'about:srcdoc#section', parent: mainFrame }
+  input('Tab')
+  input('Escape', 'keyUp')
+  expect(contents.send).not.toHaveBeenCalled()
+  input()
+  expect(contents.send).toHaveBeenCalledExactlyOnceWith(ipcChannels.windowPreviewEscape)
+  destroyed = true
+  dispose()
+  input()
+  expect(contents.send).toHaveBeenCalledTimes(1)
+  expect(contents.listenerCount('before-input-event')).toBe(0)
+})

src/main/window-ipc.ts

@@ -22,7 +22,17 @@ export function registerClipboardIpcHandlers(
 export function registerWindowIpcHandlers(
   registerHandler: typeof ipcMain.handle,
   window: BrowserWindow
-): void {
+): () => void {
+  const contents = window.webContents
+  // Sandboxed srcdoc keyboard events cannot bubble to the renderer's modal.
+  const previewEscape = (_event: Electron.Event, input: Electron.Input): void => {
+    const frame = contents.focusedFrame
+    if (input.type === 'keyDown' && input.key === 'Escape' &&
+      frame?.parent === contents.mainFrame && frame.url.startsWith('about:srcdoc')) {
+      contents.send(ipcChannels.windowPreviewEscape)
+    }
+  }
+  contents.on('before-input-event', previewEscape)
   registerHandler(ipcChannels.appShow, (event) => {
     assertTrustedSender(event, window)
     showWindow(window)
@@ -56,4 +66,5 @@ export function registerWindowIpcHandlers(
     assertTrustedSender(event, window)
     return window.isMaximized()
   })
+  return () => contents.removeListener('before-input-event', previewEscape)
 }