From 7fecf95f64066103fc243c4d09b721ea38db540e Mon Sep 17 00:00:00 2001
From: Paul Horn <paul@paul-horn.de>
Date: Thu, 10 Sep 2026 21:13:13 +0200
Subject: [PATCH 1/7] Restore files panel sidebar-only toggle

---
 src/renderer/panels/EditorPanel.tsx          | 21 ++++++++++++----
 src/renderer/panels/ExplorerSidebar.test.tsx | 25 ++++++++++++++++++++
 src/renderer/panels/ExplorerSidebar.tsx      | 11 +++++----
 3 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/src/renderer/panels/EditorPanel.tsx b/src/renderer/panels/EditorPanel.tsx
index aa247594..c860c94f 100644
--- a/src/renderer/panels/EditorPanel.tsx
+++ b/src/renderer/panels/EditorPanel.tsx
@@ -7,7 +7,7 @@ import { panelSearchStore } from '../stores/panelSearchStores'
 
 import { useEffect, useRef, useCallback, useState } from 'react'
 import type { ReactNode } from 'react'
-import { Check, ChevronDown, ChevronLeft, ChevronRight, Copy, ExternalLink, FolderOpen, Folders, Github, Search } from 'lucide-react'
+import { Check, ChevronDown, ChevronLeft, ChevronRight, Copy, ExternalLink, FolderOpen, Folders, Github, PanelLeftClose, PanelLeftOpen, Search } from 'lucide-react'
 import { perfCount, useRenderCount } from '../lib/perf/perfClient'
 import log from '../lib/logger'
 import * as monaco from 'monaco-editor'
@@ -257,6 +257,7 @@ export default function EditorPanel({
   const [markdownContent, setMarkdownContent] = useState('')
   const [loadError, setLoadError] = useState<string | null>(null)
   const [fileLoading, setFileLoading] = useState(!!filePath)
+  const [editorCollapsed, setEditorCollapsed] = useState(false)
   const toolbarRef = useRef<HTMLDivElement>(null)
   const [toolbarScroll, setToolbarScroll] = useState({ left: false, right: false })
   const [editorBackground, setEditorBackground] = useState(() => getActiveTheme().editor.colors?.['editor.background'] ?? 'var(--surface-1)')
@@ -272,6 +273,7 @@ export default function EditorPanel({
   const currentWorktree = worktreeForPanel(panel, worktrees)
   const explorerRoot = currentWorktree?.path ?? worktreeForPanel(panel, ws?.worktrees ?? [])?.path ?? ws?.rootPath ?? ''
   const explorerVisible = panel?.sidebarVisible !== false
+  const editorVisible = !editorCollapsed || !explorerVisible || !explorerRoot
   const setExplorerVisible = (visible: boolean) => useAppStore.getState().setPanelNavigation(workspaceId, panelId, panel?.sidebarView === 'search' ? 'search' : 'explorer', visible)
 
   const activePanelId = useActivePanelStore((s) => s.activePanelId)
@@ -292,7 +294,7 @@ export default function EditorPanel({
       toolbar.removeEventListener('scroll', update)
       observer.disconnect()
     }
-  }, [filePath, explorerVisible, searchVisible])
+  }, [filePath, explorerVisible, searchVisible, editorVisible])
   const setNavigationView = (view: 'explorer' | 'search') => {
     useAppStore.getState().setPanelNavigation(workspaceId, panelId, view)
   }
@@ -834,6 +836,17 @@ export default function EditorPanel({
           className="shrink-0 flex items-center gap-2 px-2.5 py-1.5 rounded-lg border border-strong text-secondary hover:bg-hover hover:text-primary disabled:opacity-40"
           title="Open in another app"
         ><ExternalLink size={13} /><span>Open</span><ChevronDown size={11} /></button>
+        <button
+          onClick={() => {
+            if (editorVisible) setExplorerVisible(true)
+            setEditorCollapsed(editorVisible)
+          }}
+          disabled={!explorerRoot}
+          className="shrink-0 p-1.5 rounded-md text-secondary hover:bg-hover hover:text-primary disabled:opacity-40"
+          title={editorVisible ? 'Show sidebar only' : 'Show editor'}
+          aria-label={editorVisible ? 'Show sidebar only' : 'Show editor'}
+          aria-pressed={!editorVisible}
+        >{editorVisible ? <PanelLeftClose size={15} /> : <PanelLeftOpen size={15} />}</button>
         <button
           onClick={() => {
             if (explorerVisible && !searchVisible) setExplorerVisible(false)
@@ -895,7 +908,7 @@ export default function EditorPanel({
         </div>
       </NodePopover>}
       <div className="files-content flex-1 min-h-0 flex" style={{ backgroundColor: editorBackground }}>
-      <div className="flex-1 min-w-0 relative">
+      <div className={`${editorVisible ? 'flex-1' : 'hidden'} min-w-0 relative`}>
         {showDiff && conflict?.kind === 'changed' && (
           <div className="absolute inset-0 z-30 bg-surface-1">
             <div ref={diffOverlayRef} className="w-full h-full" />
@@ -920,7 +933,7 @@ export default function EditorPanel({
 
       </div>
       {explorerRoot && (
-        <ExplorerSidebar visible={explorerVisible} onHide={() => setExplorerVisible(false)}>
+        <ExplorerSidebar visible={explorerVisible} fill={!editorVisible} onHide={() => setExplorerVisible(false)}>
           {searchVisible
             ? <SearchView store={searchStore} panelId={panelId} focusToken={panel?.navigationEpoch} rootPath={explorerRoot} workspaceId={workspaceId} focusInput={explorerVisible && activePanelId === panelId} onOpenMatch={(path, line, column) => { void openExplorerFiles([path], 'dock', { line, column }) }} />
             : <FileExplorer workspaceId={workspaceId} panelId={panelId} rootPath={explorerRoot} onOpenFiles={openExplorerFiles} compact />}
diff --git a/src/renderer/panels/ExplorerSidebar.test.tsx b/src/renderer/panels/ExplorerSidebar.test.tsx
index 7ca94025..68b25c77 100644
--- a/src/renderer/panels/ExplorerSidebar.test.tsx
+++ b/src/renderer/panels/ExplorerSidebar.test.tsx
@@ -32,3 +32,28 @@ it('holds at minimum width and collapses only after the second drag threshold',
   await act(async () => root.unmount())
   host.remove()
 })
+
+it('fills the panel without a resize handle and restores the sidebar width', async () => {
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  const root = createRoot(host)
+  const onHide = vi.fn()
+  const render = async (fill: boolean) => {
+    await act(async () => root.render(<ExplorerSidebar visible fill={fill} onHide={onHide}>Files</ExplorerSidebar>))
+  }
+  await render(false)
+  await act(async () => host.querySelector('[role="separator"]')!.dispatchEvent(
+    new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }),
+  ))
+  expect(host.querySelector('aside')!.style.width).toBe('276px')
+  await render(true)
+  expect(host.querySelector('aside')!.style.width).toBe('100%')
+  expect(host.querySelector('aside')!.style.maxWidth).toBe('none')
+  expect(host.querySelector('[role="separator"]')).toBeNull()
+  expect(host.textContent).toBe('Files')
+  await render(false)
+  expect(host.querySelector('aside')!.style.width).toBe('276px')
+  expect(host.querySelector('[role="separator"]')).not.toBeNull()
+  await act(async () => root.unmount())
+  host.remove()
+})
diff --git a/src/renderer/panels/ExplorerSidebar.tsx b/src/renderer/panels/ExplorerSidebar.tsx
index 79a88c2b..57e507ad 100644
--- a/src/renderer/panels/ExplorerSidebar.tsx
+++ b/src/renderer/panels/ExplorerSidebar.tsx
@@ -4,8 +4,9 @@ const MIN_WIDTH = 180
 const MAX_WIDTH = 480
 const COLLAPSE_OVERSHOOT = 64
 
-export function ExplorerSidebar({ visible, onHide, children }: {
+export function ExplorerSidebar({ visible, fill = false, onHide, children }: {
   visible: boolean
+  fill?: boolean
   onHide: () => void
   children: ReactNode
 }) {
@@ -18,12 +19,12 @@ export function ExplorerSidebar({ visible, onHide, children }: {
     ref={sidebarRef}
     aria-hidden={!visible}
     className={`relative shrink-0 h-full ${dragging ? '' : 'transition-[width,opacity] duration-200 ease-out motion-reduce:transition-none'}`}
-    style={{ width: visible ? width : 0, maxWidth: '70%', opacity: visible ? 1 : 0 }}
+    style={{ width: visible ? (fill ? '100%' : width) : 0, maxWidth: fill ? 'none' : '70%', opacity: visible ? 1 : 0 }}
   >
-    <div className="h-full overflow-hidden border-l border-subtle" style={{ visibility: visible ? 'visible' : 'hidden', transition: visible ? undefined : 'visibility 0s 200ms' }}>
-      <div className="h-full" style={{ width }}>{children}</div>
+    <div className={`h-full overflow-hidden ${fill ? '' : 'border-l border-subtle'}`} style={{ visibility: visible ? 'visible' : 'hidden', transition: visible ? undefined : 'visibility 0s 200ms' }}>
+      <div className="h-full" style={{ width: fill ? '100%' : width }}>{children}</div>
     </div>
-    {visible && <div
+    {visible && !fill && <div
       role="separator"
       aria-label="Resize file explorer"
       aria-orientation="vertical"

From 250babf8d78875db5fa1fe35abd11eda8fae262d Mon Sep 17 00:00:00 2001
From: Paul Horn <paul@paul-horn.de>
Date: Thu, 10 Sep 2026 21:31:38 +0200
Subject: [PATCH 2/7] Move file creation actions to sidebar footer and contain
 scrolling

---
 src/renderer/panels/EditorPanel.tsx   |  4 ++--
 src/renderer/sidebar/FileExplorer.tsx | 17 +++++++----------
 2 files changed, 9 insertions(+), 12 deletions(-)

diff --git a/src/renderer/panels/EditorPanel.tsx b/src/renderer/panels/EditorPanel.tsx
index c860c94f..e053efa2 100644
--- a/src/renderer/panels/EditorPanel.tsx
+++ b/src/renderer/panels/EditorPanel.tsx
@@ -6,7 +6,7 @@ import { panelSearchStore } from '../stores/panelSearchStores'
 // =============================================================================
 
 import { useEffect, useRef, useCallback, useState } from 'react'
-import type { ReactNode } from 'react'
+import type { CSSProperties, ReactNode } from 'react'
 import { Check, ChevronDown, ChevronLeft, ChevronRight, Copy, ExternalLink, FolderOpen, Folders, Github, PanelLeftClose, PanelLeftOpen, Search } from 'lucide-react'
 import { perfCount, useRenderCount } from '../lib/perf/perfClient'
 import log from '../lib/logger'
@@ -907,7 +907,7 @@ export default function EditorPanel({
           }} className="flex items-center gap-2.5 rounded-lg px-2.5 py-1.5 text-left text-[13px] text-primary hover:bg-hover focus-visible:bg-hover"><Icon size={16} className="text-muted" />{label}</button>)}
         </div>
       </NodePopover>}
-      <div className="files-content flex-1 min-h-0 flex" style={{ backgroundColor: editorBackground }}>
+      <div className="files-content flex-1 min-h-0 flex" style={{ backgroundColor: editorBackground, '--file-explorer-bg': editorBackground } as CSSProperties}>
       <div className={`${editorVisible ? 'flex-1' : 'hidden'} min-w-0 relative`}>
         {showDiff && conflict?.kind === 'changed' && (
           <div className="absolute inset-0 z-30 bg-surface-1">
diff --git a/src/renderer/sidebar/FileExplorer.tsx b/src/renderer/sidebar/FileExplorer.tsx
index babce04f..864e26b6 100644
--- a/src/renderer/sidebar/FileExplorer.tsx
+++ b/src/renderer/sidebar/FileExplorer.tsx
@@ -590,7 +590,7 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceI
 
   return (
     <div
-      className="file-explorer flex flex-col h-full"
+      className="file-explorer flex flex-col h-full min-h-0 overflow-hidden"
       // External (OS) file/folder drops anywhere in the panel import into the
       // workspace root. stopPropagation keeps the drop from bubbling to the
       // app-root handler (which would otherwise re-root the workspace).
@@ -618,12 +618,6 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceI
         subtitle={scopeControl ?? folderName}
         actions={
           <>
-            <SidebarHeaderButton onClick={() => startRootCreate('file')} title="New File">
-              <FilePlus size={13} />
-            </SidebarHeaderButton>
-            <SidebarHeaderButton onClick={() => startRootCreate('folder')} title="New Folder">
-              <FolderPlus size={13} />
-            </SidebarHeaderButton>
             <SidebarHeaderButton
               onClick={() => {
                 setSearchVisible((v) => {
@@ -658,8 +652,6 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceI
             />
           </div>
           <div className="shrink-0 flex items-center gap-1">
-            <SidebarHeaderButton onClick={() => startRootCreate('file')} title="New File"><FilePlus size={14} /></SidebarHeaderButton>
-            <SidebarHeaderButton onClick={() => startRootCreate('folder')} title="New Folder"><FolderPlus size={14} /></SidebarHeaderButton>
             <SidebarHeaderButton onClick={handleReload} title="Reload"><ArrowClockwise size={14} /></SidebarHeaderButton>
           </div>
         </div>
@@ -712,7 +704,7 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceI
       ) : (
         <div
           ref={treeContainerRef}
-          className="relative flex-1 overflow-y-auto py-1 outline-none"
+          className="relative flex-1 min-h-0 overflow-y-auto overscroll-none pt-1 pb-4 outline-none"
           // Focusable + tagged so Delete/Backspace (incl. Cmd+Backspace) deletes
           // the selection here instead of being swallowed by the canvas-level
           // shortcut handler. Focused explicitly from onSelect (draggable rows
@@ -800,6 +792,11 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceI
           )}
         </div>
       )}
+      <div className="relative shrink-0 h-10 flex items-center justify-end gap-1 px-2">
+        <div className="pointer-events-none absolute inset-x-0 -top-4 h-4" style={{ background: 'linear-gradient(to bottom, transparent, var(--file-explorer-bg, var(--surface-1)))' }} />
+        <SidebarHeaderButton onClick={() => startRootCreate('file')} title="New File"><FilePlus size={14} /></SidebarHeaderButton>
+        <SidebarHeaderButton onClick={() => startRootCreate('folder')} title="New Folder"><FolderPlus size={14} /></SidebarHeaderButton>
+      </div>
     </div>
   )
 }

From c6aaa06760b1477df138e3a0b3d3996f4bdf8e4b Mon Sep 17 00:00:00 2001
From: Paul Horn <paul@paul-horn.de>
Date: Thu, 10 Sep 2026 21:33:54 +0200
Subject: [PATCH 3/7] Consolidate local canvas, repository, and appearance
 refinements

---
 src/renderer/canvas/Canvas.tsx                |  1 +
 .../canvas/CanvasNode.groupDrag.test.tsx      | 32 ++++++++++++
 src/renderer/canvas/CanvasNode.tsx            | 42 ++++++++++-----
 src/renderer/canvas/useCanvasNodeStyle.ts     | 28 +++++-----
 src/renderer/dialogs/SkillsDialog.tsx         | 24 ++++-----
 src/renderer/lib/themeManager.test.tsx        | 42 +++++++++++++++
 src/renderer/lib/themeManager.ts              |  7 +++
 .../panels/TerminalPanel.renderScale.test.tsx |  2 +-
 src/renderer/panels/TerminalPanel.tsx         |  6 ++-
 .../repository/RepositoryOverview.tsx         |  2 +-
 src/renderer/repository/SourceControlView.tsx | 50 +++++++++---------
 .../settings/AppearanceSettings.test.tsx      | 52 +++++++++++++++++++
 src/renderer/settings/AppearanceSettings.tsx  | 29 ++++-------
 src/renderer/stores/canvas/nodesSlice.ts      | 22 +-------
 .../stores/canvasStore.lifecycle.test.ts      | 21 +++-----
 15 files changed, 240 insertions(+), 120 deletions(-)
 create mode 100644 src/renderer/lib/themeManager.test.tsx
 create mode 100644 src/renderer/settings/AppearanceSettings.test.tsx

diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 1bcaf827..fc1e47f2 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -312,6 +312,7 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
     if (!el) return
 
     const onWheel = (e: WheelEvent) => {
+      if ((e.target as Element).closest('[data-canvas-maximized="true"]')) return
       handleWheelRef.current(e as unknown as React.WheelEvent<HTMLDivElement>)
     }
 
diff --git a/src/renderer/canvas/CanvasNode.groupDrag.test.tsx b/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
index 8705048e..8e6d9d0b 100644
--- a/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
+++ b/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
@@ -335,3 +335,35 @@ describe('CanvasNode — group drag from the title bar', () => {
     expect(store.getState().nodes['B'].origin).toEqual({ x: 400, y: 0 })
   })
 })
+
+it('uses split-sized diagonal maximize controls and restores the live canvas panel', () => {
+  const wsId = useAppStore.getState().addWorkspace('WS', '/tmp/ws', 'ws-maximize')
+  useAppStore.getState().addPanel(wsId, { id: 'panel-A', type: 'editor', title: 'Editor', isDirty: false })
+  const store = freshCanvasStore()
+  addNode(store, 'A', 'panel-A', { x: 120, y: 230 }, { width: 400, height: 300 })
+  const dock = tabsDockStore('panel-A')
+  act(() => root.render(
+    <CanvasStoreProvider store={store}>
+      <CanvasNode nodeId="A" isFocused dockStoreApi={dock} renderPanel={() => <input defaultValue="keep" />} />
+    </CanvasStoreProvider>,
+  ))
+  const node = container.querySelector<HTMLElement>('[data-node-id="A"]')!
+  const input = node.querySelector('input')
+  const button = container.querySelector<HTMLButtonElement>('[aria-label="Maximize"]')!
+  expect(button.classList.contains('w-6')).toBe(true)
+  expect(button.querySelector('.lucide-maximize2')).not.toBeNull()
+  expect(button.querySelector('svg')?.getAttribute('width')).toBe('14')
+  act(() => button.click())
+  expect(node.style.position).toBe('fixed')
+  expect(node.style.width).toBe('100vw')
+  expect(node.style.height).toBe('100vh')
+  expect(container.querySelector('[data-resize-frame-for]')).toBeNull()
+  const restore = container.querySelector<HTMLButtonElement>('[aria-label="Restore"]')!
+  expect(restore.querySelector('.lucide-minimize2')).not.toBeNull()
+  act(() => restore.click())
+  expect(node.style.position).toBe('absolute')
+  expect(node.style.left).toBe('120px')
+  expect(node.style.top).toBe('230px')
+  expect(node.style.width).toBe('400px')
+  expect(node.querySelector('input')).toBe(input)
+})
diff --git a/src/renderer/canvas/CanvasNode.tsx b/src/renderer/canvas/CanvasNode.tsx
index 252d8f86..cb30c18d 100644
--- a/src/renderer/canvas/CanvasNode.tsx
+++ b/src/renderer/canvas/CanvasNode.tsx
@@ -33,11 +33,14 @@ import { Tooltip } from '../ui/Tooltip'
 import DockLayoutRenderer from '../docking/DockLayoutRenderer'
 import { confirmClosePanels } from '../lib/confirmClosePanels'
 import { collectPanelIds } from '../../shared/collectPanelIds'
-import { Maximize as ArrowsOutSimple, Minimize as ArrowsInSimple, X, Lock, LockOpen } from 'lucide-react'
+import { Maximize2, Minimize2, X, Lock, LockOpen } from 'lucide-react'
 import { PANEL_DEFINITIONS } from '../../shared/panels'
 import { captureRendererException } from '../lib/sentry'
 import { useCanvasTopOverlayTarget } from './CanvasTopOverlayContext'
 import { worktreeForPanel } from '../lib/worktreeContext'
+import { IS_MAC } from '../lib/platform'
+import { useWindowFullscreen } from '../lib/useWindowFullscreen'
+import { TRAFFIC_LIGHTS_WIDTH } from '../shells/MacWindowChrome'
 
 // Node ids already reported for missing geometry, so a bad node that keeps
 // re-rendering warns/reports once instead of spamming.
@@ -98,6 +101,23 @@ const PULSE_KEYFRAMES = `
   opacity: 0 !important;
   pointer-events: none !important;
 }
+/* Keep live panel contents mounted while escaping canvas scaling and clipping. */
+body :has([data-canvas-maximized="true"]) {
+  transform: none !important;
+  filter: none !important;
+  perspective: none !important;
+  contain: none !important;
+  will-change: auto !important;
+  overflow: visible !important;
+  z-index: auto !important;
+}
+[data-canvas-maximized="true"] { --zoom: 1; }
+[data-canvas-maximized="true"] .dock-tab-bar {
+  padding-left: var(--maximized-chrome-inset) !important;
+}
+body:has([data-canvas-maximized="true"]) [data-node-id]:not([data-canvas-maximized="true"]),
+body:has([data-canvas-maximized="true"]) [data-canvas-top-overlay],
+body:has([data-canvas-maximized="true"]) [data-resize-frame-for] { visibility: hidden; }
 `
 
 let keyframesInjected = false
@@ -132,7 +152,7 @@ function GrabButton({
         data-grab-button
         aria-label={title}
         onClick={onClick}
-        className="flex items-center justify-center w-[18px] h-[18px] rounded text-secondary hover:text-primary hover:bg-hover"
+        className="flex items-center justify-center w-6 h-6 self-center rounded-[10px] text-muted hover:text-primary hover:bg-hover"
         style={{ background: 'transparent', border: 'none', cursor: 'pointer', color: baseColor }}
       >
         {children}
@@ -141,7 +161,7 @@ function GrabButton({
   )
 }
 
-const TAB_ICON_SIZE = 12
+const TAB_ICON_SIZE = 14
 
 // -----------------------------------------------------------------------------
 // Component
@@ -159,10 +179,10 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
   useRenderCount('CanvasNode')
 
   const canvasApi = useCanvasStoreApi()
+  const windowFullscreen = useWindowFullscreen()
   const topOverlayTarget = useCanvasTopOverlayTarget()
   const nodeRef = useRef<HTMLDivElement>(null)
   const [isHovered, setIsHovered] = useState(false)
-  const [isAnimatingLayout, setIsAnimatingLayout] = useState(false)
   // True while a file/panel drag is hovering an unfocused node, so the dim
   // overlay lets the drop fall through to the panel content that owns it.
   const [fileDragOver, setFileDragOver] = useState(false)
@@ -357,10 +377,8 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
   }, [removeNode, nodeId, layout, confirmCloseForPanels, wsId])
 
   const handleToggleMaximize = useCallback(() => {
-    setIsAnimatingLayout(true)
     const viewportSize = { width: window.innerWidth, height: window.innerHeight }
     toggleMaximize(nodeId, viewportSize)
-    setTimeout(() => setIsAnimatingLayout(false), 300)
   }, [toggleMaximize, nodeId])
 
   // Spring-load: when ANY dock drag is active AND this node is maximized
@@ -452,8 +470,8 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
         onClick={(e) => { e.stopPropagation(); handleToggleMaximize() }}
       >
         {maximized
-          ? <ArrowsInSimple size={TAB_ICON_SIZE} />
-          : <ArrowsOutSimple size={TAB_ICON_SIZE} />}
+          ? <Minimize2 size={TAB_ICON_SIZE} />
+          : <Maximize2 size={TAB_ICON_SIZE} />}
       </GrabButton>
       <GrabButton
         title="Close"
@@ -480,7 +498,7 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
           onPanelRemoved={handlePanelRemoved}
           excludePanelTypes={CANVAS_EXCLUDED_TYPES}
           localOnly
-          compact
+          compact={false}
           onTabBarMouseDown={isHeaderHost ? handleHeaderMouseDown : undefined}
           trailingControls={isHeaderHost ? nodeControlButtons : undefined}
           dropDisabled={isWholeNodeDragSource}
@@ -638,7 +656,6 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
     isFocused,
     isSelected,
     activityState,
-    isAnimatingLayout,
     isHovered,
     chromeTint,
     isWholeNodeDragSource,
@@ -672,8 +689,9 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
     <div
       ref={nodeRef}
       data-node-id={nodeId}
+      data-canvas-maximized={maximized ? "true" : undefined}
       data-node-active={isFocused ? 'true' : 'false'}
-      style={containerStyle}
+      style={{ ...containerStyle, ['--maximized-chrome-inset' as string]: IS_MAC && !windowFullscreen ? `${TRAFFIC_LIGHTS_WIDTH}px` : '0px' }}
       onClick={handleClick}
       onMouseDown={handleMouseDown}
       onMouseEnter={() => setIsHovered(true)}
@@ -823,7 +841,7 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
         Mounted as a sibling (not inside the node's overflow:hidden box) so the
         strips can overhang the edge; positioned to the node's bounds and
         stacked with it. */}
-    {!isWholeNodeDragSource && (
+    {!maximized && !isWholeNodeDragSource && (
       <div
         aria-hidden
         data-resize-frame-for={nodeId}
diff --git a/src/renderer/canvas/useCanvasNodeStyle.ts b/src/renderer/canvas/useCanvasNodeStyle.ts
index 4a4c4293..ea4cc489 100644
--- a/src/renderer/canvas/useCanvasNodeStyle.ts
+++ b/src/renderer/canvas/useCanvasNodeStyle.ts
@@ -6,6 +6,7 @@
 // =============================================================================
 
 import React, { useMemo } from 'react'
+import { isMaximized } from '../../shared/types'
 import type { CanvasNodeState, NodeActivityState } from '../../shared/types'
 import { NODE_CORNER_RADIUS as CORNER_RADIUS } from './nodeAppearance'
 
@@ -45,7 +46,6 @@ interface StyleArgs {
   isFocused: boolean
   isSelected: boolean
   activityState: NodeActivityState | undefined
-  isAnimatingLayout: boolean
   isHovered: boolean
   chromeTint: { background: string; accent: string } | null
   isWholeNodeDragSource: boolean
@@ -64,7 +64,6 @@ export function useCanvasNodeStyle(args: StyleArgs) {
     isFocused,
     isSelected,
     activityState,
-    isAnimatingLayout,
     isHovered,
     chromeTint,
     isWholeNodeDragSource,
@@ -82,9 +81,7 @@ export function useCanvasNodeStyle(args: StyleArgs) {
 
     const baseTransition =
       'border-color 150ms ease, box-shadow 200ms ease, outline-color 200ms ease, transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1), opacity 150ms ease-out, filter 200ms ease'
-    const layoutTransition = isAnimatingLayout
-      ? ', left 250ms cubic-bezier(0.16, 1, 0.3, 1), top 250ms cubic-bezier(0.16, 1, 0.3, 1), width 250ms cubic-bezier(0.16, 1, 0.3, 1), height 250ms cubic-bezier(0.16, 1, 0.3, 1)'
-      : ''
+
 
     const baseOpacity = isEntering ? 0 : isExiting ? 0 : isWholeNodeDragSource ? 0 : 1
     // Focus lens: nodes outside the focused worktree recede.
@@ -112,17 +109,24 @@ export function useCanvasNodeStyle(args: StyleArgs) {
         ? `color-mix(in srgb, ${chromeTint.background} 86%, white 14%)`
         : 'var(--surface-3)',
       ['--node-chrome-accent' as any]: chromeTint?.accent ?? 'var(--focus-blue)',
-      transition: baseTransition + layoutTransition,
+      transition: baseTransition,
       filter: worktreeDim ? 'saturate(0.4)' : undefined,
       transform: isEntering ? 'scale(0.85)' : isExiting ? 'scale(0.9)' : 'scale(1)',
       opacity,
       pointerEvents: isExiting || isWholeNodeDragSource ? 'none' : undefined,
       userSelect: 'none',
+      ...(isMaximized(node) ? {
+        position: 'fixed', left: 0, top: 0, width: '100vw', height: '100vh',
+        zIndex: 50, borderRadius: 0, border: 'none', boxShadow: 'none',
+        transform: 'none', transition: 'none', filter: 'none',
+        opacity: isExiting || isWholeNodeDragSource ? 0 : 1,
+        ['--node-inner-radius' as any]: '0px',
+      } as React.CSSProperties : {}),
     }
-  }, [node, isFocused, isSelected, activityState, isAnimatingLayout, isHovered, chromeTint, isWholeNodeDragSource, worktreeDim])
+  }, [node, isFocused, isSelected, activityState, isHovered, chromeTint, isWholeNodeDragSource, worktreeDim])
 
   const glowStyle = useMemo<React.CSSProperties | null>(() => {
-    if (!node) return null
+    if (!node || isMaximized(node)) return null
     if (!(isFocused || isSelected || worktreeHighlight)) return null
     // Hide the focus glow while the node is the drag source — the source node
     // itself is hidden (containerStyle.opacity = 0 above) and the glow would
@@ -130,9 +134,7 @@ export function useCanvasNodeStyle(args: StyleArgs) {
     if (isWholeNodeDragSource) return null
     const isEntering = node.animationState === 'entering'
     const isExiting = node.animationState === 'exiting'
-    const layoutTransition = isAnimatingLayout
-      ? 'left 250ms cubic-bezier(0.16, 1, 0.3, 1), top 250ms cubic-bezier(0.16, 1, 0.3, 1), width 250ms cubic-bezier(0.16, 1, 0.3, 1), height 250ms cubic-bezier(0.16, 1, 0.3, 1), '
-      : ''
+
     return {
       position: 'absolute',
       left: node.origin.x,
@@ -157,9 +159,9 @@ export function useCanvasNodeStyle(args: StyleArgs) {
       pointerEvents: 'none',
       transform: isEntering ? 'scale(0.85)' : isExiting ? 'scale(0.9)' : 'scale(1)',
       opacity: isEntering || isExiting ? 0 : 1,
-      transition: `${layoutTransition}transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1), opacity 150ms ease-out, box-shadow 200ms ease`,
+      transition: `transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1), opacity 150ms ease-out, box-shadow 200ms ease`,
     }
-  }, [node, isFocused, isSelected, isAnimatingLayout, isWholeNodeDragSource, worktreeHighlight, worktreeColor])
+  }, [node, isFocused, isSelected, isWholeNodeDragSource, worktreeHighlight, worktreeColor])
 
   return { containerStyle, glowStyle }
 }
diff --git a/src/renderer/dialogs/SkillsDialog.tsx b/src/renderer/dialogs/SkillsDialog.tsx
index db0f9b9a..76fdf1f0 100644
--- a/src/renderer/dialogs/SkillsDialog.tsx
+++ b/src/renderer/dialogs/SkillsDialog.tsx
@@ -44,7 +44,7 @@ import {
 
 const api = () => window.electronAPI
 
-// The list of repos the curated catalog is crawled from. Linked at the bottom so
+// The list of repos the curated catalog is crawled from. Linked in the header so
 // anyone can PR a missing skill's source repo in (the CI crawler turns this into
 // skills-index.json).
 const SKILL_SOURCES_URL = 'https://github.com/0-AI-UG/cate/blob/main/registry/sources.json'
@@ -263,6 +263,15 @@ export function SkillsDialog() {
       <LeftSidebarReopen />
       <OverlayHeader title="Skills">
         {!contentSlot && <button type="button" onClick={close} className="text-sm text-muted hover:text-primary">Back</button>}
+        <button
+          type="button"
+          onClick={() => window.electronAPI?.openExternalUrl(SKILL_SOURCES_URL)}
+          className="inline-flex items-center gap-1.5 rounded-md px-2 py-1 text-xs text-secondary hover:bg-hover hover:text-primary"
+          title="Suggest a missing skill for the catalog"
+        >
+          Add a skill source
+          <ArrowSquareOut size={13} />
+        </button>
       </OverlayHeader>
       <div className="mx-auto flex w-full max-w-[1040px] min-h-0 flex-1 flex-col px-6">
         <div className="py-4 shrink-0 flex items-center gap-2">
@@ -384,19 +393,6 @@ export function SkillsDialog() {
             <div className={itemsClassName}>{visibleBrowseRows.map((e) => renderRow(e, false))}</div>
           )}
         </div>
-
-        {/* Pinned footer — PR a missing skill into the curated index. Stays put
-            below the (possibly very long) scrolling list so it's always seen. */}
-        <div className="shrink-0 border-t border-subtle px-3.5 py-2 text-[11px] text-muted">
-          Missing a skill?{' '}
-          <button
-            onClick={() => window.electronAPI?.openExternalUrl(SKILL_SOURCES_URL)}
-            className="inline-flex items-center gap-0.5 text-secondary hover:text-primary underline decoration-dotted underline-offset-2"
-          >
-            Add its source
-            <ArrowSquareOut size={11} />
-          </button>
-        </div>
       </div>
     </section>,
     contentSlot ?? document.body,
diff --git a/src/renderer/lib/themeManager.test.tsx b/src/renderer/lib/themeManager.test.tsx
new file mode 100644
index 00000000..c4b0631f
--- /dev/null
+++ b/src/renderer/lib/themeManager.test.tsx
@@ -0,0 +1,42 @@
+import { afterEach, expect, it, vi } from 'vitest'
+import { applyTheme, getActiveTheme, subscribeTheme } from './themeManager'
+import { useSettingsStore } from '../stores/settingsStore'
+import { DEFAULT_SETTINGS } from '../../shared/types'
+import { BUILT_IN_BY_ID, DEFAULT_DARK_THEME_ID, DEFAULT_LIGHT_THEME_ID } from '../../shared/themes'
+import { mergeThemeApp } from '../../shared/themeResolution'
+
+const custom = {
+  ...BUILT_IN_BY_ID[DEFAULT_DARK_THEME_ID], id: 'custom',
+  app: { 'surface-1': '#ff00ff', 'text-primary': '#abcdef', 'custom-token': '#123456' },
+}
+
+afterEach(() => {
+  useSettingsStore.setState(DEFAULT_SETTINGS)
+  applyTheme(DEFAULT_DARK_THEME_ID)
+  document.documentElement.style.removeProperty('--unrelated')
+})
+
+it.each([DEFAULT_DARK_THEME_ID, DEFAULT_LIGHT_THEME_ID, 'deleted-theme'])('fully replaces custom colors when switching to %s', (selection) => {
+  useSettingsStore.setState({ customThemes: [custom] })
+  applyTheme(custom.id)
+  expect(document.documentElement.style.getPropertyValue('--surface-1')).toBe('#ff00ff')
+  expect(document.documentElement.style.getPropertyValue('--custom-token')).toBe('#123456')
+  document.documentElement.style.setProperty('--unrelated', '42px')
+  useSettingsStore.setState({ customThemes: [] })
+  const listener = vi.fn()
+  const unsubscribe = subscribeTheme(listener)
+  try {
+    applyTheme(selection)
+    const expected = BUILT_IN_BY_ID[selection] ?? BUILT_IN_BY_ID[DEFAULT_DARK_THEME_ID]
+    expect(getActiveTheme()).toBe(expected)
+    for (const [key, value] of Object.entries(mergeThemeApp(expected))) {
+      expect(document.documentElement.style.getPropertyValue('--' + key)).toBe(value)
+    }
+    expect(document.documentElement.style.getPropertyValue('--custom-token')).toBe('')
+    expect(document.documentElement.style.getPropertyValue('--unrelated')).toBe('42px')
+    expect(document.documentElement.dataset.theme).toBe(expected.type)
+    expect(listener).toHaveBeenCalledWith(expected)
+  } finally {
+    unsubscribe()
+  }
+})
diff --git a/src/renderer/lib/themeManager.ts b/src/renderer/lib/themeManager.ts
index 11ecdd64..2886ea44 100644
--- a/src/renderer/lib/themeManager.ts
+++ b/src/renderer/lib/themeManager.ts
@@ -26,6 +26,7 @@ import { mergeThemeApp, resolveTheme as resolveThemeSelection } from '../../shar
 
 let currentTheme: Theme = BUILT_IN_BY_ID[DEFAULT_DARK_THEME_ID]
 let currentSelection: ThemeSelection = 'system'
+let appliedAppKeys = new Set<string>()
 const subscribers = new Set<(t: Theme) => void>()
 
 let mediaQuery: MediaQueryList | null = null
@@ -66,6 +67,12 @@ function injectAppVars(theme: Theme): void {
   if (typeof document === 'undefined') return
   const root = document.documentElement
   const merged = mergeThemeApp(theme)
+  // Settings-file themes can contain extra tokens absent from the base palette.
+  // Remove their old overrides when switching or deleting a theme.
+  for (const key of appliedAppKeys) {
+    if (!(key in merged)) root.style.removeProperty('--' + key)
+  }
+  appliedAppKeys = new Set(Object.keys(merged))
   for (const [key, value] of Object.entries(merged)) {
     root.style.setProperty('--' + key, value)
   }
diff --git a/src/renderer/panels/TerminalPanel.renderScale.test.tsx b/src/renderer/panels/TerminalPanel.renderScale.test.tsx
index a8a3c7e4..238fbf58 100644
--- a/src/renderer/panels/TerminalPanel.renderScale.test.tsx
+++ b/src/renderer/panels/TerminalPanel.renderScale.test.tsx
@@ -130,7 +130,7 @@ vi.mock('../lib/terminal/terminalRegistry', () => {
 
 // --- collaborators the panel pulls in but that are irrelevant here ----------
 
-const canvasState = { zoomLevel: 2.0 }
+const canvasState = { zoomLevel: 2.0, nodes: {} }
 vi.mock('../stores/CanvasStoreContext', () => ({
   useOptionalCanvasStoreApi: () => null,
   // Selectors that read state this fake doesn't model fall back, as they do
diff --git a/src/renderer/panels/TerminalPanel.tsx b/src/renderer/panels/TerminalPanel.tsx
index 7cee4517..562c6bfd 100644
--- a/src/renderer/panels/TerminalPanel.tsx
+++ b/src/renderer/panels/TerminalPanel.tsx
@@ -15,6 +15,7 @@
 import { useEffect, useRef, useState, useCallback } from 'react'
 
 import type { TerminalPanelProps } from './types'
+import { isMaximized } from '../../shared/types'
 import { terminalRegistry } from '../lib/terminal/terminalRegistry'
 import { formatTerminalPaste, type DroppedRef } from './terminalDrop'
 import { useAppStore } from '../stores/appStore'
@@ -207,7 +208,10 @@ export default function TerminalPanel({
 
   const isFocused = useOptionalCanvasStoreContext((s) => focusedNodeId(s) === nodeId, false)
   const canvasApi = useOptionalCanvasStoreApi()
-  const zoomLevel = useOptionalCanvasStoreContext((s) => s.zoomLevel, 1)
+  const zoomLevel = useOptionalCanvasStoreContext((s) => {
+    const node = nodeId ? s.nodes[nodeId] : undefined
+    return node && isMaximized(node) ? 1 : s.zoomLevel
+  }, 1)
 
   // -------------------------------------------------------------------------
   // Search handlers
diff --git a/src/renderer/repository/RepositoryOverview.tsx b/src/renderer/repository/RepositoryOverview.tsx
index 7b96970b..6dab3d2a 100644
--- a/src/renderer/repository/RepositoryOverview.tsx
+++ b/src/renderer/repository/RepositoryOverview.tsx
@@ -53,7 +53,7 @@ export default function RepositoryOverview() {
     <OverlayHeader title="Repository">
       <IconButton label="GitHub settings" onClick={() => useUIStore.getState().openSettings('source control')}><Settings2 size={15} /></IconButton>
     </OverlayHeader>
-    <div className="mx-auto flex min-h-0 w-full max-w-[1040px] flex-1 flex-col px-6 pt-4 pb-4">
+    <div className="mx-auto flex min-h-0 w-full max-w-[1040px] flex-1 flex-col px-6 pt-4">
       <div className="mb-6 flex flex-wrap items-start justify-between gap-4">
         <div className="min-w-0 flex-1">
           {repositories.length > 1 ? <select aria-label="Local repository" value={root} onChange={e => setSelected(e.target.value)} className="max-w-full rounded-lg border border-subtle bg-surface-2 px-2 py-1 text-xl font-semibold">{repositories.map(path => <option key={path} value={path}>{pathDisplayName(path)}</option>)}</select> : <h1 className="truncate text-xl font-medium">{root ? pathDisplayName(root) : 'Your repositories'}</h1>}
diff --git a/src/renderer/repository/SourceControlView.tsx b/src/renderer/repository/SourceControlView.tsx
index 8317dc9d..29e5ea30 100644
--- a/src/renderer/repository/SourceControlView.tsx
+++ b/src/renderer/repository/SourceControlView.tsx
@@ -117,21 +117,21 @@ const Section: React.FC<{
   if (count === 0) return null
 
   return (
-    <div className="mb-1">
+    <div className="mb-4 overflow-hidden rounded-lg border border-subtle">
       <div
-        className="flex items-center gap-1 px-3 py-2 text-xs font-medium text-muted cursor-pointer hover:bg-hover select-none"
+        className="flex items-center gap-2 bg-surface-1 px-4 py-3 text-[13px] font-semibold text-primary cursor-pointer hover:bg-hover select-none"
         onClick={() => setOpen(!open)}
       >
         {open ? <CaretDown size={12} /> : <CaretRight size={12} />}
         <span className="flex-1">{title}</span>
-        <span className="text-muted font-normal normal-case">{count}</span>
+        <span className="min-w-6 rounded-full bg-surface-3 px-2 py-0.5 text-center text-[11px] font-medium text-secondary tabular-nums">{count}</span>
         {actions && (
           <div className="flex items-center gap-0.5 ml-1" onClick={(e) => e.stopPropagation()}>
             {actions}
           </div>
         )}
       </div>
-      {open && <div>{children}</div>}
+      {open && <div className="divide-y divide-subtle border-t border-subtle">{children}</div>}
     </div>
   )
 }
@@ -151,15 +151,15 @@ const FileEntry: React.FC<{
   const dir = dirName(file.path)
   return (
     <div
-      className="group flex items-center gap-1 mx-1.5 my-0.5 rounded-lg px-3 py-2 text-[13px] cursor-pointer hover:bg-hover"
+      className="group flex items-center gap-2 px-4 py-3 text-[13px] cursor-pointer hover:bg-hover"
       onClick={onClick}
     >
       <span className={`w-4 text-center font-mono text-[11px] flex-shrink-0 ${statusColor(statusChar)}`}>
         {statusChar}
       </span>
-      <span className="truncate text-primary flex-1 min-w-0">
+      <span className="truncate font-medium text-primary flex-1 min-w-0">
         {fileName(file.path)}
-        {dir && <span className="text-muted ml-1">{dir}</span>}
+        {dir && <span className="text-muted ml-2 font-normal">{dir}</span>}
       </span>
       <div className="hidden group-hover:flex items-center gap-0.5 flex-shrink-0">
         {onDiscard && (
@@ -283,15 +283,15 @@ const BranchPicker: React.FC<{
   const branchCount = branches.length || 1 // at least show current
 
   return (
-    <div className="mb-1">
+    <div className="mb-4 overflow-hidden rounded-lg border border-subtle">
       {/* Section header — matches Section component style */}
       <div
-        className="flex items-center gap-1 px-3 py-2 text-xs font-medium text-muted cursor-pointer hover:bg-hover select-none"
+        className="flex items-center gap-2 bg-surface-1 px-4 py-3 text-[13px] font-semibold text-primary cursor-pointer hover:bg-hover select-none"
         onClick={() => setIsOpen(!isOpen)}
       >
         {isOpen ? <CaretDown size={12} /> : <CaretRight size={12} />}
         <span className="flex-1">Branches</span>
-        <span className="text-muted font-normal normal-case">{branchCount}</span>
+        <span className="min-w-6 rounded-full bg-surface-3 px-2 py-0.5 text-center text-[11px] font-medium text-secondary tabular-nums">{branchCount}</span>
         {!isOpen && (
           <span className="text-muted font-normal text-[10px] truncate max-w-[80px]">{currentBranch}</span>
         )}
@@ -300,7 +300,7 @@ const BranchPicker: React.FC<{
       {isOpen && (
         <div>
           {/* Search / Create */}
-          <div className="px-2 py-1">
+          <div className="border-y border-subtle bg-surface-1/50 p-3">
             {creating ? (
               <div className="flex gap-1">
                 <input
@@ -352,7 +352,7 @@ const BranchPicker: React.FC<{
             return (
               <div
                 key={b.name}
-                className={`group flex items-center gap-1 mx-1.5 my-0.5 rounded-lg px-3 py-[3px] cursor-pointer hover:bg-hover text-[12px] ${isSelectedCurrent ? 'text-primary' : 'text-secondary'}`}
+                className={`group flex items-center gap-2 border-b border-subtle last:border-b-0 px-4 py-3 cursor-pointer hover:bg-hover text-[13px] ${isSelectedCurrent ? 'text-primary' : 'text-secondary'}`}
                 onClick={() => handleCheckout(b.name)}
               >
                 <GitBranch size={11} className="flex-shrink-0" />
@@ -379,11 +379,11 @@ const BranchPicker: React.FC<{
           })}
           {filtered(remoteBranches).length > 0 && (
             <>
-              <div className="px-3 py-0.5 text-[10px] text-muted uppercase mt-1">Remote</div>
+              <div className="border-y border-subtle bg-surface-1 px-4 py-2 text-xs font-semibold text-secondary">Remote</div>
               {filtered(remoteBranches).map(b => (
                 <div
                   key={b.name}
-                  className="flex items-center gap-1 mx-1.5 my-0.5 rounded-lg px-3 py-[3px] cursor-pointer hover:bg-hover text-[12px] text-muted"
+                  className="flex items-center gap-2 border-b border-subtle last:border-b-0 px-4 py-3 cursor-pointer hover:bg-hover text-[13px] text-secondary"
                   onClick={() => handleCheckout(b.name)}
                 >
                   <GitBranch size={11} className="flex-shrink-0" />
@@ -670,8 +670,8 @@ const RepoSourceControl: React.FC<RepoSourceControlProps> = ({ rootPath, workspa
 
   return (
     <div className="flex h-full min-h-0 flex-col overflow-hidden text-[12px]" style={{ containerType: 'inline-size', containerName: 'repository' }}>
-      <nav aria-label="Repository sections" className="flex shrink-0 items-center gap-1 pb-3">
-        {(['changes', 'branches', 'history', 'worktrees'] as const).map(value => <Button variant="ghost" key={value} size="sm" aria-pressed={section === value} className={section === value ? 'bg-hover text-primary' : 'text-muted'} onClick={() => setSection(value)}>{value === 'history' ? 'History' : value[0].toUpperCase() + value.slice(1)}</Button>)}
+      <nav aria-label="Repository sections" className="mb-2 flex shrink-0 items-center gap-1 border-b border-subtle pb-3">
+        {(['changes', 'branches', 'history', 'worktrees'] as const).map(value => <Button variant="ghost" key={value} size="sm" aria-pressed={section === value} className={section === value ? 'bg-surface-3 font-semibold text-primary' : 'text-secondary'} onClick={() => setSection(value)}>{value === 'history' ? 'History' : value[0].toUpperCase() + value.slice(1)}</Button>)}
         <div className="ml-auto">{headerActions}</div>
       </nav>
       {section === 'changes' && (
@@ -701,11 +701,11 @@ const RepoSourceControl: React.FC<RepoSourceControlProps> = ({ rootPath, workspa
         </div>
       )}
 
-      <div className={section === 'changes' ? 'repository-changes-grid grid min-h-0 flex-1 grid-cols-1 gap-4 overflow-y-auto py-2' : 'min-h-0 flex-1 overflow-y-auto py-2'}>
+      <div className={section === 'changes' ? 'repository-changes-grid grid min-h-0 flex-1 grid-cols-1 gap-4 content-start overflow-y-auto pt-2 pb-6' : 'min-h-0 flex-1 overflow-y-auto pt-2 pb-6'}>
       {/* Commit area */}
       {section === 'changes' && (
-      <div className="order-2 self-start rounded-xl bg-surface-1 p-4">
-        <h2 className="mb-1 text-sm font-medium">Commit staged changes</h2>
+      <div className="order-2 self-start rounded-lg border border-subtle bg-surface-1 p-4">
+        <h2 className="mb-1 text-sm font-semibold">Commit staged changes</h2>
         <p className="mb-4 text-xs text-muted">{stagedFiles.length} staged {stagedFiles.length === 1 ? 'file' : 'files'} · {status?.current ?? 'Detached HEAD'}</p>
         <textarea
           ref={textareaRef}
@@ -754,7 +754,7 @@ const RepoSourceControl: React.FC<RepoSourceControlProps> = ({ rootPath, workspa
 
       )}
       {/* Changes share a bounded column beside the commit composer. */}
-      <div className="min-w-0 py-1">
+      <div className="min-w-0">
         {section === 'changes' && <>
         {/* Staged Changes */}
         <Section
@@ -871,13 +871,13 @@ const RepoSourceControl: React.FC<RepoSourceControlProps> = ({ rootPath, workspa
           {logEntries.map((entry) => (
             <div
               key={entry.hash}
-              className="flex items-start gap-1.5 mx-1.5 my-0.5 rounded-lg px-3 py-[4px] hover:bg-hover text-[11px] cursor-pointer"
+              className="flex items-start gap-3 px-4 py-3 hover:bg-hover text-xs cursor-pointer"
               onClick={() => openReview({ kind: 'commit', commit: entry.hash }, undefined, false, rootPath)}
             >
               <ClockCounterClockwise size={11} className="text-muted flex-shrink-0 mt-0.5" />
               <div className="flex-1 min-w-0">
-                <div className="text-primary truncate">{entry.message}</div>
-                <div className="flex items-center gap-1.5 text-muted">
+                <div className="text-[13px] font-medium text-primary truncate">{entry.message}</div>
+                <div className="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-muted">
                   <span className="font-mono">{entry.hash.slice(0, 7)}</span>
                   <span>{entry.author_name}</span>
                   <span>{relativeTime(entry.date)}</span>
@@ -899,14 +899,14 @@ const RepoSourceControl: React.FC<RepoSourceControlProps> = ({ rootPath, workspa
             <button
               type="button"
               key={wt.path}
-              className={`w-[calc(100%-0.75rem)] flex items-center gap-1.5 mx-1.5 my-0.5 rounded-lg px-3 py-[3px] hover:bg-hover text-left ${
+              className={`w-full flex items-center gap-3 px-4 py-3 hover:bg-hover text-[13px] text-left ${
                 wt.id === changesWorktree?.id ? 'text-primary bg-surface-3' : 'text-secondary'
               }`}
               title={wt.path}
               onClick={() => { setSourceControlWorktree(rootPath, wt.id); setSection('changes') }}
             >
               <GitBranch size={12} className="flex-shrink-0" />
-              <span className="truncate flex-1">{wt.label || wt.branch || '(detached)'}</span>
+              <span className="min-w-0 flex-1"><span className="block truncate font-medium">{wt.label || wt.branch || '(detached)'}</span><span className="mt-1 block truncate text-xs text-muted" title={wt.path}>{wt.path}</span></span>
               {wt.id === changesWorktree?.id && (
                 <span className="text-[10px] text-green-400/60">changes</span>
               )}
diff --git a/src/renderer/settings/AppearanceSettings.test.tsx b/src/renderer/settings/AppearanceSettings.test.tsx
new file mode 100644
index 00000000..33e7694b
--- /dev/null
+++ b/src/renderer/settings/AppearanceSettings.test.tsx
@@ -0,0 +1,52 @@
+import React, { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, expect, it, vi } from 'vitest'
+import { AppearanceSettings } from './AppearanceSettings'
+import { useSettingsStore } from '../stores/settingsStore'
+import { useThemeAndScaleHydration } from '../lib/hooks/useThemeAndScaleHydration'
+import { applyTheme, getActiveTheme } from '../lib/themeManager'
+import { DEFAULT_SETTINGS } from '../../shared/types'
+import { BUILT_IN_BY_ID, DEFAULT_DARK_THEME_ID, DEFAULT_LIGHT_THEME_ID } from '../../shared/themes'
+import { mergeThemeApp } from '../../shared/themeResolution'
+
+let host: HTMLDivElement
+let root: Root
+const custom = { ...BUILT_IN_BY_ID[DEFAULT_DARK_THEME_ID], id: 'custom', name: 'Custom', builtIn: false, app: { 'surface-1': '#ff00ff' } }
+
+function Settings() {
+  useThemeAndScaleHydration()
+  return <AppearanceSettings />
+}
+
+beforeEach(() => {
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  vi.stubGlobal('electronAPI', { ...window.electronAPI, settingsSet: vi.fn().mockResolvedValue(undefined) })
+  vi.stubGlobal('matchMedia', vi.fn(() => ({ matches: true, addEventListener: vi.fn(), removeEventListener: vi.fn() })))
+  useSettingsStore.setState({ ...DEFAULT_SETTINGS, customThemes: [custom] })
+  host = document.createElement('div')
+  document.body.appendChild(host)
+  root = createRoot(host)
+})
+
+afterEach(() => {
+  act(() => root.unmount())
+  host.remove()
+  useSettingsStore.setState(DEFAULT_SETTINGS)
+  applyTheme(DEFAULT_DARK_THEME_ID)
+  vi.unstubAllGlobals()
+})
+
+it.each(['system', 'custom'])('restores the standard system palette when deleting its custom theme from %s mode', (selection) => {
+  useSettingsStore.setState({ activeThemeId: selection, systemDarkThemeId: custom.id, systemLightThemeId: custom.id })
+  act(() => root.render(<Settings />))
+  expect(document.documentElement.style.getPropertyValue('--surface-1')).toBe('#ff00ff')
+  act(() => host.querySelector<HTMLButtonElement>('[aria-label="Remove theme"]')!.click())
+  act(() => host.querySelector<HTMLButtonElement>('[aria-label="Confirm removal"]')!.click())
+  const settings = useSettingsStore.getState()
+  expect(settings.customThemes).toEqual([])
+  expect(settings.activeThemeId).toBe('system')
+  expect(settings.systemDarkThemeId).toBe(DEFAULT_DARK_THEME_ID)
+  expect(settings.systemLightThemeId).toBe(DEFAULT_LIGHT_THEME_ID)
+  expect(getActiveTheme().id).toBe(DEFAULT_DARK_THEME_ID)
+  expect(document.documentElement.style.getPropertyValue('--surface-1')).toBe(mergeThemeApp(BUILT_IN_BY_ID[DEFAULT_DARK_THEME_ID])['surface-1'])
+})
diff --git a/src/renderer/settings/AppearanceSettings.tsx b/src/renderer/settings/AppearanceSettings.tsx
index 02611d72..fcead86a 100644
--- a/src/renderer/settings/AppearanceSettings.tsx
+++ b/src/renderer/settings/AppearanceSettings.tsx
@@ -5,7 +5,8 @@ import { useSettingsStore } from '../stores/settingsStore'
 import { SettingRow, Select, NumberInput, TextInput, Toggle, SearchableBlock, SecondaryButton } from './SettingsComponents'
 import type { Theme } from '../../shared/types'
 import { validateTheme } from '../../shared/theme'
-import { BASE_DARK, BASE_LIGHT, BUILT_IN_THEMES } from '../../shared/themes'
+import { BUILT_IN_THEMES, DEFAULT_DARK_THEME_ID, DEFAULT_LIGHT_THEME_ID } from '../../shared/themes'
+import { mergeThemeApp, resolveTheme } from '../../shared/themeResolution'
 import { errorMessage } from '../lib/errorMessage'
 import { InlineNotice } from '../ui/InlineNotice'
 
@@ -16,18 +17,6 @@ const UI_SCALE_OPTIONS = [0.8, 0.9, 1.0, 1.1, 1.2, 1.3, 1.4, 1.5].map((s) => ({
   label: `${Math.round(s * 100)}%`,
 }))
 
-/** Merge a theme's partial app map over its base — used for swatch previews. */
-function appColors(theme: Theme): Record<string, string> {
-  return { ...(theme.type === 'light' ? BASE_LIGHT : BASE_DARK), ...theme.app }
-}
-
-/** Resolve the complete theme mapped to an OS appearance for System preview. */
-function systemTheme(themes: Theme[], id: string, type: 'light' | 'dark'): Theme {
-  return themes.find((theme) => theme.id === id)
-    ?? themes.find((theme) => theme.type === type)
-    ?? BUILT_IN_THEMES[0]
-}
-
 /** Ensure an id is unique against the existing theme list, suffixing -2, -3… */
 function uniqueId(id: string, taken: Set<string>): string {
   if (!taken.has(id)) return id
@@ -102,8 +91,8 @@ export function AppearanceSettings() {
     }
     store.setSetting('customThemes', customThemes.filter((t) => t.id !== id))
     if (activeThemeId === id) store.setSetting('activeThemeId', 'system')
-    if (store.systemDarkThemeId === id) store.setSetting('systemDarkThemeId', 'dark-warm')
-    if (store.systemLightThemeId === id) store.setSetting('systemLightThemeId', 'light-subtle')
+    if (store.systemDarkThemeId === id) store.setSetting('systemDarkThemeId', DEFAULT_DARK_THEME_ID)
+    if (store.systemLightThemeId === id) store.setSetting('systemLightThemeId', DEFAULT_LIGHT_THEME_ID)
     setConfirmDeleteId(null)
   }
 
@@ -128,8 +117,8 @@ export function AppearanceSettings() {
       <div role="radiogroup" aria-label="Theme" className="grid grid-cols-2 gap-2 pb-3 lg:grid-cols-3">
         <SystemCard
           active={isSystem}
-          lightTheme={systemTheme(allThemes, store.systemLightThemeId, 'light')}
-          darkTheme={systemTheme(allThemes, store.systemDarkThemeId, 'dark')}
+          lightTheme={resolveTheme(store, 'system', false)}
+          darkTheme={resolveTheme(store, 'system', true)}
           onClick={() => store.setSetting('activeThemeId', 'system')}
         />
         {allThemes.map((theme) => (
@@ -254,7 +243,7 @@ function CardShell({
 }
 
 function SwatchPreview({ theme }: { theme: Theme }) {
-  const c = appColors(theme)
+  const c = mergeThemeApp(theme)
   return (
     <div className="flex items-center justify-center gap-5 py-1">
       <ThemeOrb base={c['surface-1']} shade={c['surface-6']} accent={c['focus-blue']} />
@@ -336,8 +325,8 @@ function ThemeCard({
 function SystemCard({
   active, lightTheme, darkTheme, onClick,
 }: { active: boolean; lightTheme: Theme; darkTheme: Theme; onClick: () => void }) {
-  const light = appColors(lightTheme)
-  const dark = appColors(darkTheme)
+  const light = mergeThemeApp(lightTheme)
+  const dark = mergeThemeApp(darkTheme)
   return (
     <CardShell active={active} onClick={onClick}>
       <div className="flex items-center justify-center gap-5 py-1">
diff --git a/src/renderer/stores/canvas/nodesSlice.ts b/src/renderer/stores/canvas/nodesSlice.ts
index 0dba374d..f7aef789 100644
--- a/src/renderer/stores/canvas/nodesSlice.ts
+++ b/src/renderer/stores/canvas/nodesSlice.ts
@@ -195,7 +195,7 @@ export function createNodesSlice(set: CanvasSet, get: CanvasGet): NodesActions {
       set({ selectionActive: false })
     },
 
-    toggleMaximize(id, viewportSize) {
+    toggleMaximize(id, _viewportSize) {
       const state = get()
       const node = state.nodes[id]
       if (!node) return
@@ -213,29 +213,11 @@ export function createNodesSlice(set: CanvasSet, get: CanvasGet): NodesActions {
           preMaximizeSize: undefined,
         }
       } else {
-        // Save current geometry and maximize to fill visible canvas area
-        const cs = state.containerSize
-        const topLeft = get().viewToCanvas({ x: 0, y: 0 })
-        const bottomRight = get().viewToCanvas({
-          x: cs.width || viewportSize.width,
-          y: cs.height || viewportSize.height,
-        })
-        // The canvas tab bar floats over the viewport (32px tall). Leave
-        // another 8px below it, but fill the left, right, and bottom edges.
-        const topInset = 40 / state.zoomLevel
-
+        // Full-window presentation preserves the original canvas geometry.
         updated = {
           ...node,
           preMaximizeOrigin: { ...node.origin },
           preMaximizeSize: { ...node.size },
-          origin: {
-            x: topLeft.x,
-            y: topLeft.y + topInset,
-          },
-          size: {
-            width: bottomRight.x - topLeft.x,
-            height: (bottomRight.y - topLeft.y) - topInset,
-          },
         }
       }
 
diff --git a/src/renderer/stores/canvasStore.lifecycle.test.ts b/src/renderer/stores/canvasStore.lifecycle.test.ts
index 0cc8418c..eae76d22 100644
--- a/src/renderer/stores/canvasStore.lifecycle.test.ts
+++ b/src/renderer/stores/canvasStore.lifecycle.test.ts
@@ -237,7 +237,7 @@ describe('viewport math', () => {
     expect(store.getState().zoomLevel).toBe(1.5)
   })
 
-  it('toggleMaximize fills the visible canvas and restores exactly on toggle back', () => {
+  it('toggleMaximize preserves canvas geometry and restores exactly on toggle back', () => {
     const store = createCanvasStore()
     const id = store.getState().addNode('p', 'editor', { x: 100, y: 100 }, { width: 300, height: 200 })
     store.getState().setContainerSize({ width: 1200, height: 800 })
@@ -245,8 +245,8 @@ describe('viewport math', () => {
 
     store.getState().toggleMaximize(id, { width: 1200, height: 800 })
     const maxed = store.getState().nodes[id]
-    expect(maxed.origin).toEqual({ x: 0, y: 40 })
-    expect(maxed.size).toEqual({ width: 1200, height: 760 })
+    expect(maxed.origin).toEqual({ x: 100, y: 100 })
+    expect(maxed.size).toEqual({ width: 300, height: 200 })
     expect(maxed.preMaximizeOrigin).toEqual({ x: 100, y: 100 })
     expect(focusedNodeId(store.getState())).toBe(id)
 
@@ -258,7 +258,7 @@ describe('viewport math', () => {
     expect(restored.preMaximizeSize).toBeUndefined()
   })
 
-  it.each([0.5, 1.04, 2])('maximize keeps screen-space edges and header spacing at zoom %s', (zoom) => {
+  it.each([0.5, 1.04, 2])('maximize preserves canvas geometry at zoom %s', (zoom) => {
     const store = createCanvasStore()
     const id = store.getState().addNode('p', 'editor', { x: 100, y: 100 }, { width: 300, height: 200 })
     store.getState().setContainerSize({ width: 1200, height: 800 })
@@ -267,15 +267,10 @@ describe('viewport math', () => {
     // The canvas can be smaller than the window because of sidebars/docks.
     store.getState().toggleMaximize(id, { width: 1600, height: 1000 })
     const node = store.getState().nodes[id]
-    const topLeft = store.getState().canvasToView(node.origin)
-    const bottomRight = store.getState().canvasToView({
-      x: node.origin.x + node.size.width,
-      y: node.origin.y + node.size.height,
-    })
-    expect(topLeft.x).toBeCloseTo(0)
-    expect(topLeft.y).toBeCloseTo(40)
-    expect(bottomRight.x).toBeCloseTo(1200)
-    expect(bottomRight.y).toBeCloseTo(800)
+    expect(node.origin).toEqual({ x: 100, y: 100 })
+    expect(node.size).toEqual({ width: 300, height: 200 })
+    expect(store.getState().zoomLevel).toBe(zoom)
+    expect(store.getState().viewportOffset).toEqual({ x: 137, y: -83 })
   })
 })
 

From d9fa22a414e9e8becb4b4ace27a7f443c8116903 Mon Sep 17 00:00:00 2001
From: Paul Horn <paul@paul-horn.de>
Date: Thu, 10 Sep 2026 23:06:33 +0200
Subject: [PATCH 4/7] Unify file previews and add screenshot annotation

---
 AGENTS.md                                     |   5 +-
 e2e/detached-panels.spec.ts                   |   4 +-
 src/main/ipc/recentScreenshot.test.ts         |  56 ++++-
 src/main/ipc/recentScreenshot.ts              |  38 +++-
 src/main/runtime/runtime-loopback.test.ts     |   8 +-
 src/preload/index.ts                          |   2 +
 .../canvas/Canvas.targetInteraction.test.tsx  |   2 +-
 .../canvas/Canvas.topOverlay.test.tsx         |  38 ++++
 src/renderer/canvas/Canvas.tsx                |  16 +-
 .../canvas/CanvasNode.groupDrag.test.tsx      |  15 +-
 src/renderer/canvas/CanvasNode.tsx            |  58 ++++--
 src/renderer/canvas/Minimap.test.tsx          |   6 +-
 .../canvas/RecentScreenshotButton.test.tsx    |  86 ++++++++
 .../canvas/RecentScreenshotButton.tsx         | 191 +++++++++++++++++-
 src/renderer/canvas/ScreenshotDrawing.tsx     | 112 ++++++++++
 src/renderer/canvas/useCanvasNodeStyle.ts     |   2 +-
 src/renderer/dialogs/SkillsDialog.tsx         |   7 +-
 src/renderer/docking/DockResizeHandle.tsx     |  12 +-
 .../docking/DockSplitContainer.drag.test.tsx  |   8 +-
 .../docking/DockSplitContainer.test.ts        |   6 +-
 src/renderer/docking/DockTabContextMenu.tsx   |   3 +-
 src/renderer/docking/splitSizing.test.ts      |  14 +-
 src/renderer/docking/splitSizing.ts           |   2 +-
 .../hooks/useShortcuts.activeCanvas.test.tsx  |   2 +-
 src/renderer/lib/e2eHarness.ts                |   2 +-
 src/renderer/lib/editor/editorDocuments.ts    |   6 +-
 src/renderer/lib/editor/useFileSync.ts        |   2 +-
 src/renderer/lib/fs/fileRouting.ts            |   4 -
 src/renderer/lib/panelTargetPicker.test.ts    |   2 +-
 .../lib/workspace/sessionSerialize.ts         |   1 -
 src/renderer/lib/worktreeContext.test.ts      |   2 +-
 src/renderer/lib/worktreeContext.ts           |   2 +-
 src/renderer/panels/AgentChangesView.tsx      |   4 +-
 .../panels/BrowserDownloadsPopover.tsx        |   4 +-
 src/renderer/panels/BrowserMenu.tsx           |  80 ++++----
 src/renderer/panels/BrowserPanel.tsx          |   3 +-
 .../panels/EditorPanel.navigation.test.tsx    |  14 +-
 src/renderer/panels/EditorPanel.tsx           |  22 +-
 ...est.tsx => FilePreview.component.test.tsx} |  16 +-
 .../{DocumentPanel.tsx => FilePreview.tsx}    |  13 +-
 .../panels/GitReviewPanel.lifecycle.test.tsx  |  11 +-
 src/renderer/panels/GitReviewPanel.tsx        |   3 +-
 src/renderer/panels/PanelHost.test.tsx        |   2 +-
 src/renderer/panels/ReviewControls.tsx        |   3 +-
 src/renderer/panels/UrlSuggestions.tsx        |  15 +-
 src/renderer/panels/documentBytes.ts          |   2 +-
 src/renderer/panels/registry.ts               |  14 +-
 src/renderer/shells/DockWindowShell.tsx       |   2 +-
 src/renderer/shells/MainWindowShell.tsx       |   1 +
 .../sidebar/FileExplorer.performance.test.tsx |  25 ++-
 src/renderer/sidebar/FileExplorer.tsx         |  32 ++-
 src/renderer/sidebar/explorerRefresh.ts       |  10 +-
 src/renderer/stores/appStore/panelSlice.ts    |  18 --
 src/renderer/stores/appStore/types.ts         |   1 -
 src/renderer/stores/canvasStore.ts            |   2 +-
 .../stores/canvasVisibleNodes.test.tsx        |  19 ++
 .../stores/detachedDockPlacement.test.ts      |   2 +-
 src/renderer/styles/globals.css               |  19 ++
 src/renderer/ui/CommandPalette.tsx            |   2 +-
 src/renderer/ui/Popover.tsx                   |   2 +-
 src/renderer/ui/SharedPrimitives.test.tsx     |   9 +-
 src/shared/cliPermissions.ts                  |   2 +-
 src/shared/electron-api.d.ts                  |   1 +
 src/shared/ipc-channels.ts                    |   2 +
 src/shared/panels.test.ts                     |   9 +-
 src/shared/panels.ts                          |  16 +-
 src/shared/recentScreenshot.ts                |   2 +
 src/shared/types.ts                           |   9 +-
 68 files changed, 858 insertions(+), 247 deletions(-)
 create mode 100644 src/renderer/canvas/ScreenshotDrawing.tsx
 rename src/renderer/panels/{DocumentPanel.component.test.tsx => FilePreview.component.test.tsx} (92%)
 rename src/renderer/panels/{DocumentPanel.tsx => FilePreview.tsx} (96%)

diff --git a/AGENTS.md b/AGENTS.md
index 419d25ef..0f689a11 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -65,12 +65,11 @@ The canvas (`Canvas.tsx`) positions nodes using CSS transforms. Panel positions
 
 Panel definitions are centralised in `src/shared/panels.ts`. The detachable panel
 types (`PanelType` in `src/shared/types.ts`) are: terminal, browser, editor,
-canvas, agent, document, review. Renderer components live in `src/renderer/panels/`:
-- **EditorPanel** — Monaco Editor with integrated Files and Search navigation
+canvas, agent, review. Renderer components live in `src/renderer/panels/`:
+- **EditorPanel** — Files with Monaco editing, image/PDF/DOCX previews, and integrated Files and Search navigation
 - **TerminalPanel** — xterm.js terminal with WebGL renderer, backed by node-pty
 - **BrowserPanel** — embedded webview (file:// allowed for local HTML)
 - **CanvasPanel** — nested canvas
-- **DocumentPanel** — PDF / docx / image preview
 - **AgentPanel** — Codex agent thread (sidebar + dock)
 
 The file tree and Search are hosted by EditorPanel. Source Control and Pull
diff --git a/e2e/detached-panels.spec.ts b/e2e/detached-panels.spec.ts
index ca232764..c4a588d2 100644
--- a/e2e/detached-panels.spec.ts
+++ b/e2e/detached-panels.spec.ts
@@ -70,11 +70,11 @@ async function chooseNativeMenu(choice: string) {
   }, choice)
 }
 
-for (const type of ['terminal', 'browser', 'editor', 'canvas', 'agent', 'document', 'review', 'surface'] as const) {
+for (const type of ['terminal', 'browser', 'editor', 'canvas', 'agent', 'review', 'surface'] as const) {
   test(`${type}: real detach, palette, overview reveal and owner-routed close`, async () => {
     const image = path.join(directory, 'preview.svg')
     writeFileSync(image, '<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40"><rect width="40" height="40" fill="red"/></svg>')
-    const id = await main.evaluate(({ type, image }) => window.__cateE2E!.createPanel(type, type === 'document' ? image : undefined), { type, image })
+    const id = await main.evaluate(({ type, image }) => window.__cateE2E!.createPanel(type, type === 'editor' ? image : undefined), { type, image })
     expect(id).toBeTruthy()
     const detached = await detach(id)
     await expect.poll(() => main.evaluate(id => window.__cateE2E!.panels().some(p => p.id === id), id)).toBe(false)
diff --git a/src/main/ipc/recentScreenshot.test.ts b/src/main/ipc/recentScreenshot.test.ts
index 9df6664f..96836fb6 100644
--- a/src/main/ipc/recentScreenshot.test.ts
+++ b/src/main/ipc/recentScreenshot.test.ts
@@ -1,28 +1,32 @@
 import path from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { RECENT_SCREENSHOT_GET, RECENT_SCREENSHOT_DRAG, RECENT_SCREENSHOT_CHANGED } from '../../shared/ipc-channels'
+import { RECENT_SCREENSHOT_GET, RECENT_SCREENSHOT_DRAG, RECENT_SCREENSHOT_CHANGED, RECENT_SCREENSHOT_SAVE } from '../../shared/ipc-channels'
 import { registerRecentScreenshotHandlers } from './recentScreenshot'
 
 const mocks = vi.hoisted(() => ({
   handle: vi.fn(), on: vi.fn(), watch: vi.fn(), close: vi.fn(), watcherOn: vi.fn(),
   run: vi.fn(), stat: vi.fn(), thumbnail: vi.fn(), broadcast: vi.fn(), grant: vi.fn(), drag: vi.fn(),
+  runtimeGrant: vi.fn(), mkdir: vi.fn(), writeFile: vi.fn(), decode: vi.fn(),
 }))
 vi.mock('node:child_process', () => ({ execFile: (...args: unknown[]) => mocks.run(...args) }))
 vi.mock('node:util', () => ({ promisify: () => (...args: unknown[]) => new Promise((resolve, reject) => {
   mocks.run(...args, (error: Error | null, stdout: string, stderr: string) => error ? reject(error) : resolve({ stdout, stderr }))
 }) }))
-vi.mock('node:fs/promises', () => ({ stat: mocks.stat }))
+vi.mock('node:fs/promises', () => ({ stat: mocks.stat, writeFile: mocks.writeFile, mkdir: mocks.mkdir }))
 vi.mock('chokidar', () => ({ watch: mocks.watch }))
 vi.mock('electron', () => ({
   app: { getPath: (key: string) => key === 'desktop' ? '/desktop' : '/home', on: mocks.on },
   ipcMain: { handle: mocks.handle },
   BrowserWindow: { getAllWindows: () => [{ id: 1 }, { id: 2 }] },
-  nativeImage: { createThumbnailFromPath: mocks.thumbnail, createFromDataURL: () => 'icon' },
+  nativeImage: { createThumbnailFromPath: mocks.thumbnail, createFromDataURL: mocks.decode },
 }))
 vi.mock('../windowRegistry', () => ({ broadcastToAll: mocks.broadcast, windowFromEvent: () => ({ id: 1 }) }))
 vi.mock('./pathValidation', () => ({ grantFileAccess: mocks.grant }))
+vi.mock('../runtime/runtimeManager', () => ({
+  resolveLocator: (path: string) => ({ path, runtime: { grantFileAccess: mocks.runtimeGrant } }),
+}))
 
-const invoke = (channel: string, value?: string) => mocks.handle.mock.calls.find(([name]) => name === channel)![1]({ sender: { startDrag: mocks.drag } }, value)
+const invoke = (channel: string, value?: string, dataUrl?: string) => mocks.handle.mock.calls.find(([name]) => name === channel)![1]({ sender: { startDrag: mocks.drag } }, value, dataUrl)
 const settle = async () => { for (let i = 0; i < 20; i++) await Promise.resolve() }
 const emit = async (event: string, filePath: string) => {
   mocks.watcherOn.mock.calls.find(([name]) => name === event)![1](filePath)
@@ -33,6 +37,9 @@ beforeEach(async () => {
   vi.resetAllMocks()
   vi.useFakeTimers()
   vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
+  mocks.grant.mockImplementation(async (_windowId, filePath) => filePath)
+  mocks.decode.mockReturnValue('icon')
+  mocks.runtimeGrant.mockResolvedValue(undefined)
   mocks.run.mockImplementation((_command, _args, _options, callback) => callback(null, '', ''))
   mocks.watch.mockReturnValue({ on: mocks.watcherOn, close: mocks.close })
   mocks.stat.mockImplementation(async () => ({ isFile: () => true, mtimeMs: Date.now() }))
@@ -53,9 +60,30 @@ describe('recent macOS screenshot', () => {
     expect(mocks.run).toHaveBeenCalledWith('/usr/bin/xattr', ['-p', 'com.apple.metadata:kMDItemIsScreenCapture', '/desktop/localized-name.png'], expect.anything(), expect.any(Function))
     expect(mocks.grant).toHaveBeenCalledWith(1, '/desktop/localized-name.png')
     expect(mocks.grant).toHaveBeenCalledWith(2, '/desktop/localized-name.png')
+    expect(mocks.runtimeGrant).toHaveBeenCalledWith('/desktop/localized-name.png', 1)
+    expect(mocks.runtimeGrant).toHaveBeenCalledWith('/desktop/localized-name.png', 2)
     expect(await invoke(RECENT_SCREENSHOT_GET)).toMatchObject([{ filePath: '/desktop/localized-name.png' }])
   })
 
+  it('waits for daemon access before publishing and regrants on a fresh read', async () => {
+    const releases: Array<() => void> = []
+    mocks.runtimeGrant.mockImplementation(() => new Promise<void>(resolve => { releases.push(resolve) }))
+    await emit('add', '/desktop/waiting.png')
+    expect(mocks.broadcast).not.toHaveBeenCalled()
+    mocks.runtimeGrant.mockResolvedValue(undefined)
+    // Both windows must acknowledge the grant.
+    expect(releases).toHaveLength(2)
+    releases[0]()
+    await settle()
+    expect(mocks.broadcast).not.toHaveBeenCalled()
+    releases[1]()
+    await settle()
+    expect(mocks.broadcast).toHaveBeenCalledOnce()
+    mocks.runtimeGrant.mockClear()
+    expect(await invoke(RECENT_SCREENSHOT_GET)).toHaveLength(1)
+    expect(mocks.runtimeGrant).toHaveBeenCalledWith('/desktop/waiting.png', 1)
+  })
+
   it('retains recent screenshots without a deadline', async () => {
     await emit('add', '/desktop/first.png')
     await vi.advanceTimersByTimeAsync(30_000)
@@ -104,6 +132,26 @@ describe('recent macOS screenshot', () => {
     expect(await invoke(RECENT_SCREENSHOT_GET)).toHaveLength(4)
   })
 
+  it('stores annotated copies, grants access and publishes them as new screenshots', async () => {
+    await emit('add', '/desktop/shot.png')
+    const [shot] = await invoke(RECENT_SCREENSHOT_GET)
+    const png = Buffer.from('full-resolution-annotated-png')
+    mocks.decode.mockReturnValue({ isEmpty: () => false, toPNG: () => png })
+    const saved = await invoke(RECENT_SCREENSHOT_SAVE, shot.id, 'data:image/png;base64,test')
+    expect(saved.annotated).toBe(true)
+    expect(saved.filePath).toMatch(/^\/home\/screenshots\/shot-annotated-.*\.png$/)
+    expect(mocks.writeFile).toHaveBeenCalledWith(saved.filePath, png, { flag: 'wx' })
+    expect(mocks.runtimeGrant).toHaveBeenCalledWith(saved.filePath, 1)
+    expect(mocks.runtimeGrant).toHaveBeenCalledWith(saved.filePath, 2)
+    expect(await invoke(RECENT_SCREENSHOT_GET)).toEqual([saved, shot])
+    expect(mocks.broadcast).toHaveBeenLastCalledWith(RECENT_SCREENSHOT_CHANGED, [saved, shot])
+    await invoke(RECENT_SCREENSHOT_DRAG, saved.id)
+    expect(mocks.drag).toHaveBeenCalledWith({ file: saved.filePath, icon: expect.anything() })
+    const evicted = await invoke(RECENT_SCREENSHOT_SAVE, 'evicted-id', 'data:image/png;base64,test')
+    expect(evicted.annotated).toBe(true)
+    expect(evicted.filePath).not.toBe(saved.filePath)
+  })
+
   it('switches to a custom screenshot directory and closes watchers on quit', async () => {
     mocks.run.mockImplementation((_command, _args, _options, callback) => callback(null, '~/Pictures/Shots\n', ''))
     await vi.advanceTimersByTimeAsync(5000)
diff --git a/src/main/ipc/recentScreenshot.ts b/src/main/ipc/recentScreenshot.ts
index 232ad039..b16301c9 100644
--- a/src/main/ipc/recentScreenshot.ts
+++ b/src/main/ipc/recentScreenshot.ts
@@ -2,17 +2,27 @@ import { app, BrowserWindow, ipcMain, nativeImage } from 'electron'
 import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import path from 'node:path'
-import { stat } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { stat, writeFile, mkdir } from 'node:fs/promises'
 import { watch, type FSWatcher } from 'chokidar'
 import type { RecentScreenshot } from '../../shared/recentScreenshot'
-import { RECENT_SCREENSHOT_GET, RECENT_SCREENSHOT_CHANGED, RECENT_SCREENSHOT_DRAG } from '../../shared/ipc-channels'
+import { RECENT_SCREENSHOT_GET, RECENT_SCREENSHOT_CHANGED, RECENT_SCREENSHOT_DRAG, RECENT_SCREENSHOT_SAVE } from '../../shared/ipc-channels'
 import { broadcastToAll, windowFromEvent } from '../windowRegistry'
 import { grantFileAccess } from './pathValidation'
 import { wrapHandler } from './handlerError'
 import log from '../logger'
+import { resolveLocator } from '../runtime/runtimeManager'
 
 const run = promisify(execFile)
 
+async function grantScreenshotAccess(windowId: number, filePath: string): Promise<void> {
+  const safePath = await grantFileAccess(windowId, filePath)
+  const { runtime, path: runtimePath } = resolveLocator(safePath)
+  // Binary reads run in the daemon, which owns a separate permission map.
+  // Complete its grant before publishing a thumbnail that can be opened.
+  await runtime.grantFileAccess(runtimePath, windowId)
+}
+
 export function registerRecentScreenshotHandlers(): void {
   let current: RecentScreenshot[] = []
   let watcher: FSWatcher | undefined
@@ -24,7 +34,7 @@ export function registerRecentScreenshotHandlers(): void {
   ipcMain.handle(RECENT_SCREENSHOT_GET, wrapHandler('[recentScreenshot:get]', async (event) => {
     const win = windowFromEvent(event)
     if (!win) return []
-    await Promise.all(current.map(screenshot => grantFileAccess(win.id, screenshot.filePath)))
+    await Promise.all(current.map(screenshot => grantScreenshotAccess(win.id, screenshot.filePath)))
     return current
   }))
   ipcMain.handle(RECENT_SCREENSHOT_DRAG, wrapHandler('[recentScreenshot:drag]', async (event, id: string) => {
@@ -38,6 +48,26 @@ export function registerRecentScreenshotHandlers(): void {
     })
   }))
 
+  ipcMain.handle(RECENT_SCREENSHOT_SAVE, wrapHandler('[recentScreenshot:save]', async (event, id: string, dataUrl: string) => {
+    const win = windowFromEvent(event)
+    const screenshot = current.find(shot => shot.id === id)
+    if (!win) throw new Error('Screenshot window is no longer available.')
+    if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) throw new Error('Expected a PNG image.')
+    const image = nativeImage.createFromDataURL(dataUrl)
+    if (image.isEmpty()) throw new Error('Could not read the annotated image.')
+    const directory = path.join(app.getPath('userData'), 'screenshots')
+    await mkdir(directory, { recursive: true })
+    const name = screenshot ? path.basename(screenshot.filePath, path.extname(screenshot.filePath)) : 'screenshot'
+    const filePath = path.join(directory, `${name}-annotated-${randomUUID()}.png`)
+    await writeFile(filePath, image.toPNG(), { flag: 'wx' })
+    const thumbnail = await nativeImage.createThumbnailFromPath(filePath, { width: 128, height: 128 })
+    await Promise.all(BrowserWindow.getAllWindows().map(window => grantScreenshotAccess(window.id, filePath)))
+    const saved: RecentScreenshot = { id: randomUUID(), filePath, dataUrl: thumbnail.toDataURL(), annotated: true }
+    current = [saved, ...current].slice(0, 5)
+    broadcastToAll(RECENT_SCREENSHOT_CHANGED, current)
+    return saved
+  }))
+
   if (process.platform !== 'darwin') return
 
   const inspect = async (filePath: string) => {
@@ -49,7 +79,7 @@ export function registerRecentScreenshotHandlers(): void {
       await run('/usr/bin/xattr', ['-p', 'com.apple.metadata:kMDItemIsScreenCapture', filePath], { timeout: 2000 })
       const thumbnail = await nativeImage.createThumbnailFromPath(filePath, { width: 128, height: 128 })
       if (stopped || thumbnail.isEmpty() || info.mtimeMs <= newestMtime) return
-      await Promise.all(BrowserWindow.getAllWindows().map(win => grantFileAccess(win.id, filePath)))
+      await Promise.all(BrowserWindow.getAllWindows().map(win => grantScreenshotAccess(win.id, filePath)))
       if (stopped || info.mtimeMs <= newestMtime) return
       newestMtime = info.mtimeMs
       current = [{ id: `${filePath}:${info.mtimeMs}`, filePath, dataUrl: thumbnail.toDataURL() },
diff --git a/src/main/runtime/runtime-loopback.test.ts b/src/main/runtime/runtime-loopback.test.ts
index caf215c9..c124284f 100644
--- a/src/main/runtime/runtime-loopback.test.ts
+++ b/src/main/runtime/runtime-loopback.test.ts
@@ -175,15 +175,19 @@ describe('runtime loopback (real daemon capabilities over the wire)', () => {
     // A file OUTSIDE any allowed root (not under rootDir, not under tmpdir): the
     // daemon's strict validation must reject it until the grant is forwarded.
     const outsideDir = await fs.realpath(await fs.mkdtemp(path.join(process.cwd(), 'cate-grant-')))
-    const outsideFile = path.join(outsideDir, 'granted.txt')
-    await fs.writeFile(outsideFile, 'secret\n')
+    const outsideFile = path.join(outsideDir, 'screenshot.png')
+    const original = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+a3ioAAAAASUVORK5CYII=', 'base64')
+    await fs.writeFile(outsideFile, original)
     try {
       await expect(remote.validatePathStrict(outsideFile, 1)).rejects.toThrow(/Access denied/)
+      await expect(remote.file.readBinary(outsideFile, { ownerWindowId: 1 })).rejects.toThrow(/Access denied/)
       await remote.grantFileAccess(outsideFile, 1)
       // Same window id now passes the daemon's authoritative strict check.
       await expect(remote.validatePathStrict(outsideFile, 1)).resolves.toBe(outsideFile)
+      await expect(remote.file.readBinary(outsideFile, { ownerWindowId: 1 })).resolves.toEqual(original)
       // A different window without the grant is still denied.
       await expect(remote.validatePathStrict(outsideFile, 2)).rejects.toThrow(/Access denied/)
+      await expect(remote.file.readBinary(outsideFile, { ownerWindowId: 2 })).rejects.toThrow(/Access denied/)
     } finally {
       clearFileGrantsForWindow(1)
       await fs.rm(outsideDir, { recursive: true, force: true })
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 52db4981..2c6700a8 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -224,6 +224,7 @@ import {
   RECENT_SCREENSHOT_GET,
   RECENT_SCREENSHOT_CHANGED,
   RECENT_SCREENSHOT_DRAG,
+  RECENT_SCREENSHOT_SAVE,
   AGENT_HARNESS_GET_PANEL_URL,
   AGENT_HARNESS_GET_USAGE_URL,
   PULL_REQUESTS_LIST,
@@ -485,6 +486,7 @@ const invokeForwarders = {
   nativeFileDrag: makeInvoker<'nativeFileDrag'>(NATIVE_FILE_DRAG),
   getRecentScreenshot: makeInvoker<'getRecentScreenshot'>(RECENT_SCREENSHOT_GET),
   dragRecentScreenshot: makeInvoker<'dragRecentScreenshot'>(RECENT_SCREENSHOT_DRAG),
+  saveRecentScreenshot: makeInvoker<'saveRecentScreenshot'>(RECENT_SCREENSHOT_SAVE),
   onRecentScreenshotChanged(callback: (screenshot: RecentScreenshot[]) => void): () => void {
     return createIpcListener(RECENT_SCREENSHOT_CHANGED, callback)
   },
diff --git a/src/renderer/canvas/Canvas.targetInteraction.test.tsx b/src/renderer/canvas/Canvas.targetInteraction.test.tsx
index 9b3de379..dd35a6cf 100644
--- a/src/renderer/canvas/Canvas.targetInteraction.test.tsx
+++ b/src/renderer/canvas/Canvas.targetInteraction.test.tsx
@@ -78,7 +78,7 @@ function startTarget(availability: 'new' | 'existing' | 'both', onSelected = vi.
 }
 
 describe('canvas chrome and panel-target gestures', () => {
-  const panelTypes: PanelType[] = ['terminal', 'browser', 'editor', 'agent', 'document', 'review']
+  const panelTypes: PanelType[] = ['terminal', 'browser', 'editor', 'agent', 'review']
   it.each(panelTypes.flatMap((panelType) => [0.75, 1, 1.5].map((zoom) => ({ panelType, zoom }))))(
     '$panelType creation at zoom $zoom preserves focus and offers multiple recommendations', ({ panelType, zoom }) => {
       store.setState({ zoomLevel: zoom })
diff --git a/src/renderer/canvas/Canvas.topOverlay.test.tsx b/src/renderer/canvas/Canvas.topOverlay.test.tsx
index 12c01c9e..fe63f62d 100644
--- a/src/renderer/canvas/Canvas.topOverlay.test.tsx
+++ b/src/renderer/canvas/Canvas.topOverlay.test.tsx
@@ -59,6 +59,37 @@ afterEach(() => {
 })
 
 describe('Canvas top overlay', () => {
+  it('preserves viewport measurements and pan through maximize and restore', () => {
+    const observers: ResizeObserverCallback[] = []
+    vi.stubGlobal('ResizeObserver', class {
+      constructor(callback: ResizeObserverCallback) { observers.push(callback) }
+      observe() {}
+      disconnect() {}
+    })
+    let bounds = new DOMRect(0, 0, 1000, 600)
+    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(() => bounds)
+    const store = createCanvasStore()
+    act(() => root.render(<CanvasStoreProvider store={store}><Canvas panelId="canvas-one" /></CanvasStoreProvider>))
+    const notify = (width: number, height: number) => act(() => {
+      bounds = new DOMRect(0, 0, width, height)
+      for (const callback of observers) callback([{ contentRect: bounds } as ResizeObserverEntry], {} as ResizeObserver)
+    })
+    notify(1000, 600)
+    act(() => store.getState().setZoomAndOffset(0.5, { x: 20, y: 30 }))
+    let id = ''
+    act(() => {
+      id = store.getState().addNode('terminal', 'terminal', { x: 200, y: 200 }, { width: 640, height: 400 })
+      store.getState().toggleMaximize(id, { width: 1100, height: 700 })
+    })
+    notify(1000, 1)
+    notify(1100, 700)
+    expect(store.getState().containerSize).toEqual({ width: 1000, height: 600 })
+    act(() => store.getState().toggleMaximize(id, { width: 1100, height: 700 }))
+    notify(1000, 600)
+    expect(store.getState().viewportOffset).toEqual({ x: 20, y: 30 })
+    expect(store.getState().zoomLevel).toBe(0.5)
+  })
+
   it('portals above-panel canvas chrome into one transformed screen-space layer', () => {
     const store = createCanvasStore()
     act(() => store.getState().setZoomAndOffset(2, { x: 30, y: 40 }))
@@ -80,5 +111,12 @@ describe('Canvas top overlay', () => {
     expect(overlay.querySelector('[data-glow-probe]')).not.toBeNull()
     expect(overlay.querySelector('[data-toolbar-probe]')).not.toBeNull()
     expect(container.querySelector('[data-canvas-marquee]')).toBeNull()
+
+    const nodeId = store.getState().addNode('editor', 'editor', { x: 100, y: 100 }, { width: 400, height: 300 })
+    act(() => store.getState().toggleMaximize(nodeId, { width: 1280, height: 800 }))
+    expect(overlay.hidden).toBe(true)
+    act(() => store.getState().toggleMaximize(nodeId, { width: 1280, height: 800 }))
+    expect(overlay.hidden).toBe(false)
+    expect(world.style.transform).toBe('scale(2) translate(15px, 20px)')
   })
 })
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index fc1e47f2..fc4f483b 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -191,6 +191,7 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
 
   const marquee = useUIStore((s) => s.marquee)
   const showSettings = useUIStore((s) => s.showSettings)
+  const hasMaximizedNode = useCanvasStoreContext((s) => Object.values(s.nodes).some((node) => node.preMaximizeOrigin != null))
   // Idle cursor reflects the active tool (React owns idle; useCanvasInteraction
   // overrides to 'grabbing' during an active pan and hands control back on release).
   const handToolActive = useUIStore((s) => s.activeTool === 'hand')
@@ -368,8 +369,19 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
 
     let prevRect = el.getBoundingClientRect()
     let prevWindowWidth = window.innerWidth
+    let wasMaximized = Object.values(canvasApi.getState().nodes).some((node) => node.preMaximizeOrigin != null)
 
     const observer = new ResizeObserver((entries) => {
+      const maximized = Object.values(canvasApi.getState().nodes).some((node) => node.preMaximizeOrigin != null)
+      const leavingMaximize = wasMaximized && !maximized
+      wasMaximized = maximized
+      // Maximizing changes layout ancestry, not the saved canvas viewport.
+      // Ignore those measurements and do not pan when restoring the layout.
+      if (maximized) {
+        prevRect = el.getBoundingClientRect()
+        prevWindowWidth = window.innerWidth
+        return
+      }
       for (const entry of entries) {
         const size = {
           width: entry.contentRect.width,
@@ -392,7 +404,7 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
       // structural jumps: only compensate when the right edge moved by less than
       // a quarter of the pane width.
       const structuralJump = Math.abs(dRight) > rect.width * 0.25
-      if (!windowResized && !structuralJump && Math.abs(dLeft) < 0.5 && Math.abs(dRight) > 0.5) {
+      if (!leavingMaximize && !windowResized && !structuralJump && Math.abs(dLeft) < 0.5 && Math.abs(dRight) > 0.5) {
         const { viewportOffset } = canvasApi.getState()
         canvasApi.setState({ viewportOffset: { x: viewportOffset.x + dRight, y: viewportOffset.y } })
       }
@@ -712,7 +724,7 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
         <div
           ref={topOverlayRef}
           data-canvas-top-overlay={panelId ?? ''}
-          hidden={showSettings}
+          hidden={showSettings || hasMaximizedNode}
           style={{
             position: 'fixed',
             overflow: 'clip',
diff --git a/src/renderer/canvas/CanvasNode.groupDrag.test.tsx b/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
index 8e6d9d0b..2ca525c9 100644
--- a/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
+++ b/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
@@ -349,21 +349,26 @@ it('uses split-sized diagonal maximize controls and restores the live canvas pan
   ))
   const node = container.querySelector<HTMLElement>('[data-node-id="A"]')!
   const input = node.querySelector('input')
+  expect(node.querySelector('.dock-tab-bar')?.classList.contains('min-h-[26px]')).toBe(true)
   const button = container.querySelector<HTMLButtonElement>('[aria-label="Maximize"]')!
-  expect(button.classList.contains('w-6')).toBe(true)
+  expect(button.classList.contains('w-[22px]')).toBe(true)
   expect(button.querySelector('.lucide-maximize2')).not.toBeNull()
-  expect(button.querySelector('svg')?.getAttribute('width')).toBe('14')
+  expect(button.querySelector('svg')?.getAttribute('width')).toBe('12')
   act(() => button.click())
-  expect(node.style.position).toBe('fixed')
-  expect(node.style.width).toBe('100vw')
-  expect(node.style.height).toBe('100vh')
+  expect(node.style.position).toBe('absolute')
+  expect(node.style.width).toBe('100%')
+  expect(node.style.height).toBe('100%')
   expect(container.querySelector('[data-resize-frame-for]')).toBeNull()
   const restore = container.querySelector<HTMLButtonElement>('[aria-label="Restore"]')!
   expect(restore.querySelector('.lucide-minimize2')).not.toBeNull()
+  expect(restore.classList.contains('w-6')).toBe(true)
+  expect(restore.querySelector('svg')?.getAttribute('width')).toBe('14')
+  expect(node.querySelector('.dock-tab-bar')?.classList.contains('app-header-bar')).toBe(true)
   act(() => restore.click())
   expect(node.style.position).toBe('absolute')
   expect(node.style.left).toBe('120px')
   expect(node.style.top).toBe('230px')
   expect(node.style.width).toBe('400px')
   expect(node.querySelector('input')).toBe(input)
+  expect(node.querySelector('.dock-tab-bar')?.classList.contains('min-h-[26px]')).toBe(true)
 })
diff --git a/src/renderer/canvas/CanvasNode.tsx b/src/renderer/canvas/CanvasNode.tsx
index cb30c18d..11ca4537 100644
--- a/src/renderer/canvas/CanvasNode.tsx
+++ b/src/renderer/canvas/CanvasNode.tsx
@@ -38,9 +38,6 @@ import { PANEL_DEFINITIONS } from '../../shared/panels'
 import { captureRendererException } from '../lib/sentry'
 import { useCanvasTopOverlayTarget } from './CanvasTopOverlayContext'
 import { worktreeForPanel } from '../lib/worktreeContext'
-import { IS_MAC } from '../lib/platform'
-import { useWindowFullscreen } from '../lib/useWindowFullscreen'
-import { TRAFFIC_LIGHTS_WIDTH } from '../shells/MacWindowChrome'
 
 // Node ids already reported for missing geometry, so a bad node that keeps
 // re-rendering warns/reports once instead of spamming.
@@ -101,8 +98,10 @@ const PULSE_KEYFRAMES = `
   opacity: 0 !important;
   pointer-events: none !important;
 }
-/* Keep live panel contents mounted while escaping canvas scaling and clipping. */
-body :has([data-canvas-maximized="true"]) {
+/* The shell excludes the workspace sidebars and spans every dock split.
+   Keep panel contents mounted while the shell becomes its containing block. */
+[data-panel-maximize-root] :has([data-canvas-maximized="true"]) {
+  position: static !important;
   transform: none !important;
   filter: none !important;
   perspective: none !important;
@@ -112,18 +111,33 @@ body :has([data-canvas-maximized="true"]) {
   z-index: auto !important;
 }
 [data-canvas-maximized="true"] { --zoom: 1; }
-[data-canvas-maximized="true"] .dock-tab-bar {
-  padding-left: var(--maximized-chrome-inset) !important;
+[data-canvas-container]:has([data-canvas-maximized="true"]) {
+  position: absolute !important;
+  inset: 0;
+  width: 100% !important;
+  height: 100% !important;
+  overflow: clip !important;
+}
+[data-dock-stack-id]:has([data-canvas-maximized="true"]) > .dock-tab-bar {
+  display: none;
+}
+/* Hide sibling branches along the path to the maximized panel. This also
+   hides persistent browser slots in other splits without unmounting them. */
+[data-panel-maximize-root]:has([data-canvas-maximized="true"]) > :not(:has([data-canvas-maximized="true"])):not([data-canvas-maximized="true"]),
+[data-panel-maximize-root] :has([data-canvas-maximized="true"]) > :not(:has([data-canvas-maximized="true"])):not([data-canvas-maximized="true"]) {
+  visibility: hidden;
 }
-body:has([data-canvas-maximized="true"]) [data-node-id]:not([data-canvas-maximized="true"]),
-body:has([data-canvas-maximized="true"]) [data-canvas-top-overlay],
-body:has([data-canvas-maximized="true"]) [data-resize-frame-for] { visibility: hidden; }
 `
 
 let keyframesInjected = false
 function ensureKeyframes() {
   if (keyframesInjected) return
   if (typeof document === 'undefined') return
+  // Replace earlier module versions during hot reload, including the old
+  // window-wide maximize rules, instead of accumulating conflicting styles.
+  for (const previous of document.head.querySelectorAll('style')) {
+    if (previous.textContent?.includes('@keyframes pulseActivity')) previous.remove()
+  }
   const style = document.createElement('style')
   style.textContent = PULSE_KEYFRAMES
   document.head.appendChild(style)
@@ -138,11 +152,13 @@ function GrabButton({
   title,
   onClick,
   color,
+  compact,
   children,
 }: {
   title: string
   onClick: (e: React.MouseEvent) => void
   color?: string
+  compact: boolean
   children: React.ReactNode
 }) {
   const baseColor = color ?? 'var(--text-secondary)'
@@ -152,7 +168,7 @@ function GrabButton({
         data-grab-button
         aria-label={title}
         onClick={onClick}
-        className="flex items-center justify-center w-6 h-6 self-center rounded-[10px] text-muted hover:text-primary hover:bg-hover"
+        className={`flex items-center justify-center self-center rounded-[10px] text-muted hover:text-primary hover:bg-hover ${compact ? 'w-[22px] h-[22px]' : 'w-6 h-6'}`}
         style={{ background: 'transparent', border: 'none', cursor: 'pointer', color: baseColor }}
       >
         {children}
@@ -161,7 +177,6 @@ function GrabButton({
   )
 }
 
-const TAB_ICON_SIZE = 14
 
 // -----------------------------------------------------------------------------
 // Component
@@ -179,7 +194,6 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
   useRenderCount('CanvasNode')
 
   const canvasApi = useCanvasStoreApi()
-  const windowFullscreen = useWindowFullscreen()
   const topOverlayTarget = useCanvasTopOverlayTarget()
   const nodeRef = useRef<HTMLDivElement>(null)
   const [isHovered, setIsHovered] = useState(false)
@@ -454,30 +468,34 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
     return () => canvasApi.getState().setNodeActiveWorktree(nodeId, null)
   }, [nodeId, canvasApi])
 
+  const tabIconSize = maximized ? 14 : 12
   const nodeControlButtons = (
     <>
       <GrabButton
+        compact={!maximized}
         title={node?.isPinned ? 'Unlock' : 'Lock'}
         onClick={(e) => { e.stopPropagation(); handleTogglePin() }}
         color={node?.isPinned ? 'var(--focus-blue)' : undefined}
       >
         {node?.isPinned
-          ? <Lock size={TAB_ICON_SIZE} />
-          : <LockOpen size={TAB_ICON_SIZE} />}
+          ? <Lock size={tabIconSize} />
+          : <LockOpen size={tabIconSize} />}
       </GrabButton>
       <GrabButton
+        compact={!maximized}
         title={maximized ? 'Restore' : 'Maximize'}
         onClick={(e) => { e.stopPropagation(); handleToggleMaximize() }}
       >
         {maximized
-          ? <Minimize2 size={TAB_ICON_SIZE} />
-          : <Maximize2 size={TAB_ICON_SIZE} />}
+          ? <Minimize2 size={tabIconSize} />
+          : <Maximize2 size={tabIconSize} />}
       </GrabButton>
       <GrabButton
+        compact={!maximized}
         title="Close"
         onClick={(e) => { e.stopPropagation(); handleClose() }}
       >
-        <X size={TAB_ICON_SIZE} />
+        <X size={tabIconSize} />
       </GrabButton>
     </>
   )
@@ -498,7 +516,7 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
           onPanelRemoved={handlePanelRemoved}
           excludePanelTypes={CANVAS_EXCLUDED_TYPES}
           localOnly
-          compact={false}
+          compact={!maximized}
           onTabBarMouseDown={isHeaderHost ? handleHeaderMouseDown : undefined}
           trailingControls={isHeaderHost ? nodeControlButtons : undefined}
           dropDisabled={isWholeNodeDragSource}
@@ -691,7 +709,7 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
       data-node-id={nodeId}
       data-canvas-maximized={maximized ? "true" : undefined}
       data-node-active={isFocused ? 'true' : 'false'}
-      style={{ ...containerStyle, ['--maximized-chrome-inset' as string]: IS_MAC && !windowFullscreen ? `${TRAFFIC_LIGHTS_WIDTH}px` : '0px' }}
+      style={containerStyle}
       onClick={handleClick}
       onMouseDown={handleMouseDown}
       onMouseEnter={() => setIsHovered(true)}
diff --git a/src/renderer/canvas/Minimap.test.tsx b/src/renderer/canvas/Minimap.test.tsx
index 356a83c1..1f16fa41 100644
--- a/src/renderer/canvas/Minimap.test.tsx
+++ b/src/renderer/canvas/Minimap.test.tsx
@@ -5,7 +5,7 @@ import { PANEL_DEFINITIONS } from '../../shared/panels'
 const h = vi.hoisted(() => ({
   canvas: {
     nodes: {
-      one: { id: 'one', origin: { x: 0, y: 0 }, size: { width: 600, height: 400 }, dockLayout: { type: 'tabs', id: 'one', panelIds: ['document'], activeIndex: 0 } },
+      one: { id: 'one', origin: { x: 0, y: 0 }, size: { width: 600, height: 400 }, dockLayout: { type: 'tabs', id: 'one', panelIds: ['editor'], activeIndex: 0 } },
       two: { id: 'two', origin: { x: 700, y: 0 }, size: { width: 600, height: 400 }, dockLayout: { type: 'tabs', id: 'two', panelIds: ['review'], activeIndex: 0 } },
     },
     zoomLevel: 1, containerSize: { width: 1000, height: 800 }, viewportOffset: { x: 0, y: 0 },
@@ -17,7 +17,7 @@ vi.mock('../stores/CanvasStoreContext', () => ({
 }))
 vi.mock('../stores/appStore', () => ({
   useAppStore: (select: any) => select({ selectedWorkspaceId: 'ws' }),
-  useWorkspacePanels: () => ({ document: { type: 'document' }, review: { type: 'review' } }),
+  useWorkspacePanels: () => ({ editor: { type: 'editor' }, review: { type: 'review' } }),
 }))
 vi.mock('../hooks/useAgentPanelInfo', () => ({ useAgentInfoByPanel: () => ({}) }))
 vi.mock('./worktree/useWorktreeMembership', () => ({ useWorktreeMembership: () => ({ groups: [] }) }))
@@ -30,7 +30,7 @@ it('uses registered document and review colors in the minimap', () => {
   try {
     act(() => root.render(<Minimap />))
     const colors = [...host.querySelectorAll<HTMLElement>('[style]')].map(element => element.style.backgroundColor)
-    for (const type of ['document', 'review'] as const) {
+    for (const type of ['editor', 'review'] as const) {
       expect(colors).toContain(`var(--panel-${type}, ${PANEL_DEFINITIONS[type].mutedColor})`)
     }
   } finally { act(() => root.unmount()) }
diff --git a/src/renderer/canvas/RecentScreenshotButton.test.tsx b/src/renderer/canvas/RecentScreenshotButton.test.tsx
index 7e1a1011..cd8bdfd9 100644
--- a/src/renderer/canvas/RecentScreenshotButton.test.tsx
+++ b/src/renderer/canvas/RecentScreenshotButton.test.tsx
@@ -73,3 +73,89 @@ it('does not crash the canvas when an older preload lacks screenshot APIs', asyn
     vi.unstubAllGlobals()
   }
 })
+
+it('opens clicked screenshots, navigates with overlay controls and keys, and closes the viewer', async () => {
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  const originalAPI = window.electronAPI
+  let nextImageWidth = 800
+  let nextImageHeight = window.innerHeight - 160
+  vi.stubGlobal('Image', class {
+    src = ''
+    naturalWidth = nextImageWidth
+    naturalHeight = nextImageHeight
+    decode = async () => {}
+  })
+  const originalBytes = new Uint8Array([137, 80, 78, 71]).buffer
+  const shots = ['first', 'second', 'third'].map(id => ({ id, filePath: `/${id}.png`, dataUrl: `data:image/png;base64,${id}` }))
+  window.electronAPI = {
+    ...originalAPI,
+    getRecentScreenshot: vi.fn().mockResolvedValue(shots),
+    fsReadBinary: vi.fn().mockResolvedValue(originalBytes),
+    shellOpenPath: vi.fn().mockResolvedValue({ ok: true }),
+    onRecentScreenshotChanged: vi.fn(() => () => {}),
+    dragRecentScreenshot: vi.fn().mockResolvedValue(undefined),
+  }
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  const root = createRoot(host)
+  const dialog = () => document.querySelector('[role="dialog"]')!
+  const key = (value: string) => act(async () => document.activeElement!.dispatchEvent(new KeyboardEvent('keydown', { key: value, bubbles: true })))
+  const expectOriginal = (index: number) => {
+    expect(window.electronAPI.fsReadBinary).toHaveBeenLastCalledWith(shots[index].filePath)
+    expect(dialog().querySelector('img')?.getAttribute('src')).toBe('data:image/png;base64,iVBORw==')
+  }
+  try {
+    await act(async () => root.render(<RecentScreenshotButton />))
+    const thumbnail = host.querySelectorAll<HTMLButtonElement>('[draggable="true"]')[1]
+    act(() => thumbnail.focus())
+    await act(async () => thumbnail.click())
+    expectOriginal(1)
+    expect(dialog().contains(document.activeElement)).toBe(true)
+    nextImageWidth = 4000
+    nextImageHeight = 100
+    await key('ArrowRight')
+    expectOriginal(2)
+    expect(parseFloat((dialog().querySelector('img') as HTMLImageElement).style.height)).toBeCloseTo((window.innerWidth - 96) / 40)
+    expect((dialog().querySelector('img') as HTMLImageElement).style.width).toBe(`${window.innerWidth - 96}px`)
+    nextImageWidth = 800
+    nextImageHeight = window.innerHeight - 160
+    await key('ArrowRight')
+    expectOriginal(0)
+    await key('ArrowLeft')
+    expectOriginal(2)
+    await key('ArrowLeft')
+    expectOriginal(1)
+    await act(async () => (dialog().querySelector('[aria-label="Next screenshot"]') as HTMLButtonElement).click())
+    expectOriginal(2)
+    await act(async () => (dialog().querySelector('[aria-label="Previous screenshot"]') as HTMLButtonElement).click())
+    expectOriginal(1)
+    await key('Tab')
+    expect(document.activeElement?.getAttribute('aria-label')).toBe('Edit screenshot')
+    expect(dialog().querySelector('img')?.className).toContain('rounded-xl')
+    await act(async () => (dialog().querySelector('[aria-label="Edit screenshot"]') as HTMLButtonElement).click())
+    expect(window.electronAPI.shellOpenPath).not.toHaveBeenCalled()
+    expect(dialog().querySelector('[aria-label="Draw on screenshot"]')).not.toBeNull()
+    await act(async () => (dialog().querySelector('[aria-label="Edit screenshot"]') as HTMLButtonElement).click())
+    expect(dialog().querySelector('[aria-label="Download screenshot"]')?.getAttribute('href')).toBe('data:image/png;base64,iVBORw==')
+    expect(dialog().querySelector('[aria-label="Download screenshot"]')?.getAttribute('download')).toBe('second.png')
+    await act(async () => (dialog().querySelector('[aria-label="Zoom in"]') as HTMLButtonElement).click())
+    expect(dialog().querySelector('[aria-label="Fit screenshot"]')?.textContent).toBe('120%')
+    await act(async () => (dialog().querySelector('[aria-label="Fit screenshot"]') as HTMLButtonElement).click())
+    expect(dialog().querySelector('[aria-label="Fit screenshot"]')?.textContent).toBe('100%')
+    await key('Escape')
+    expect(dialog()).toBeNull()
+    expect(document.activeElement).toBe(thumbnail)
+    await act(async () => thumbnail.click())
+    await act(async () => (dialog().querySelector('[aria-label="Close screenshot preview"]') as HTMLButtonElement).click())
+    expect(dialog()).toBeNull()
+    await act(async () => thumbnail.dispatchEvent(new Event('dragstart', { bubbles: true, cancelable: true })))
+    await act(async () => thumbnail.click())
+    expect(dialog()).toBeNull()
+    expect(window.electronAPI.dragRecentScreenshot).toHaveBeenCalledWith('second')
+  } finally {
+    act(() => root.unmount())
+    host.remove()
+    window.electronAPI = originalAPI
+    vi.unstubAllGlobals()
+  }
+})
diff --git a/src/renderer/canvas/RecentScreenshotButton.tsx b/src/renderer/canvas/RecentScreenshotButton.tsx
index a74fadf2..49a3024c 100644
--- a/src/renderer/canvas/RecentScreenshotButton.tsx
+++ b/src/renderer/canvas/RecentScreenshotButton.tsx
@@ -1,13 +1,174 @@
-import { useEffect, useState } from 'react'
-import { X } from '@phosphor-icons/react'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { CaretLeft, CaretRight, DownloadSimple, Minus, PencilSimple, Plus, X } from '@phosphor-icons/react'
 import type { RecentScreenshot } from '../../shared/recentScreenshot'
 import { Tooltip } from '../ui/Tooltip'
+import { createPortal } from 'react-dom'
+import { ScreenshotDrawing } from './ScreenshotDrawing'
+
+function ScreenshotViewer({ screenshots, initialIndex, onClose, onSaved }: {
+  screenshots: RecentScreenshot[]
+  initialIndex: number
+  onClose: () => void
+  onSaved: (screenshot: RecentScreenshot) => void
+}) {
+  const [index, setIndex] = useState(initialIndex)
+  const [image, setImage] = useState<{ id: string; url: string; width: number; height: number } | null>(null)
+  const [errorId, setErrorId] = useState<string | null>(null)
+  const [zoom, setZoom] = useState<number | null>(null)
+  const [viewport, setViewport] = useState({ width: window.innerWidth, height: window.innerHeight })
+  const [drawingToolbarHost, setDrawingToolbarHost] = useState<HTMLDivElement | null>(null)
+  const [editing, setEditing] = useState(false)
+  const [direction, setDirection] = useState(1)
+  const scrollRef = useRef<HTMLDivElement>(null)
+  useLayoutEffect(() => {
+    if (scrollRef.current) { scrollRef.current.scrollTop = 0; scrollRef.current.scrollLeft = 0 }
+  }, [image?.id])
+  const imageElementRef = useRef<HTMLDivElement>(null)
+  const directionRef = useRef(direction)
+  directionRef.current = direction
+  const dialogRef = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    const resize = () => setViewport({ width: window.innerWidth, height: window.innerHeight })
+    window.addEventListener('resize', resize)
+    const previous = document.activeElement
+    dialogRef.current?.focus({ preventScroll: true })
+    return () => {
+      window.removeEventListener('resize', resize)
+      if (previous instanceof HTMLElement && previous.isConnected) previous.focus({ preventScroll: true })
+    }
+  }, [])
+  const screenshot = screenshots[index]
+  useEffect(() => {
+    let active = true
+    setErrorId(null)
+    void window.electronAPI.fsReadBinary(screenshot.filePath).then(async bytes => {
+      if (!active) return
+      // Cate allows data: images, but its content security policy blocks blob: URLs.
+      const data = new Uint8Array(bytes)
+      let binary = ''
+      for (let offset = 0; offset < data.length; offset += 8192) {
+        binary += String.fromCharCode(...data.subarray(offset, offset + 8192))
+      }
+      const extension = screenshot.filePath.split('.').pop()?.toLowerCase()
+      const format = extension === 'jpg' ? 'jpeg' : extension === 'tif' ? 'tiff' : extension
+      const url = `data:image/${format || 'png'};base64,${btoa(binary)}`
+      const decoded = new Image()
+      decoded.src = url
+      await decoded.decode()
+      if (!active) return
+      const previous = imageElementRef.current
+      if (previous?.animate && !window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+        const animation = previous.animate([
+          { opacity: 1, transform: 'translateX(0)' },
+          { opacity: 0, transform: `translateX(${-directionRef.current * 28}px)` },
+        ], { duration: 120, easing: 'ease-in', fill: 'forwards' })
+        await animation.finished.catch(() => {})
+        if (!active) { animation.cancel(); return }
+      }
+      setZoom(null)
+      setImage({ id: screenshot.id, url, width: decoded.naturalWidth, height: decoded.naturalHeight })
+    }).catch(() => {
+      if (active) setErrorId(screenshot.id)
+    })
+    return () => {
+      active = false
+    }
+  }, [screenshot.id, screenshot.filePath])
+
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent) => {
+      if (!['ArrowLeft', 'ArrowRight', 'Escape', 'Tab'].includes(event.key)) return
+      event.preventDefault()
+      event.stopImmediatePropagation()
+      if (event.key === 'Escape') { if (editing) setEditing(false); else onClose(); return }
+      if (event.key === 'Tab') {
+        const buttons = Array.from(dialogRef.current?.querySelectorAll<HTMLElement>('button:not(:disabled), a[href]') ?? [])
+        const current = buttons.indexOf(document.activeElement as HTMLElement)
+        buttons[(current + (event.shiftKey ? -1 : 1) + buttons.length) % buttons.length]?.focus()
+        return
+      }
+      if (editing) return
+      setDirection(event.key === 'ArrowLeft' ? -1 : 1)
+      setIndex(current => (current + (event.key === 'ArrowLeft' ? -1 : 1) + screenshots.length) % screenshots.length)
+    }
+    document.addEventListener('keydown', onKey, true)
+    return () => document.removeEventListener('keydown', onKey, true)
+  }, [screenshots.length, onClose, editing])
+
+  const displayHeight = Math.max(80, viewport.height - 160)
+  const fit = image ? Math.min(1, Math.max(1, viewport.width - 96) / image.width, displayHeight / image.height) : 1
+  const scale = zoom ?? fit
+  const controlClass = 'flex h-9 w-9 shrink-0 items-center justify-center rounded-full bg-white/10 text-white/90 transition-colors hover:bg-white/20 hover:text-white focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white disabled:opacity-30'
+
+  return createPortal(
+    <div className="titlebar-no-drag fixed inset-0 z-[100000] bg-black/90" onClick={onClose}
+      onPointerDown={event => event.stopPropagation()} onPointerMove={event => event.stopPropagation()}
+      onMouseDown={event => event.stopPropagation()} onMouseMove={event => event.stopPropagation()}
+      onWheel={event => event.stopPropagation()}>
+      <div ref={dialogRef} role="dialog" aria-modal="true" aria-label="Screenshot preview" tabIndex={-1}
+        className="flex h-full flex-col outline-none">
+        <div ref={setDrawingToolbarHost} className="absolute left-1/2 top-3 z-20 -translate-x-1/2" />
+        <div className="absolute right-3 top-3 z-10 flex gap-2" onClick={event => event.stopPropagation()}>
+          <button type="button" aria-label="Edit screenshot" title="Draw on screenshot" className={`${controlClass} backdrop-blur-md`}
+            disabled={!image || image.id !== screenshot.id} aria-pressed={editing}
+            onClick={() => setEditing(value => !value)}><PencilSimple size={18} /></button>
+          {image?.id === screenshot.id && <a href={image.url} download={screenshot.filePath.split('/').pop()}
+            aria-label="Download screenshot" title="Download screenshot" className={`${controlClass} backdrop-blur-md`}><DownloadSimple size={18} /></a>}
+          <button type="button" aria-label="Close screenshot preview" title="Close (Esc)"
+            className={`${controlClass} backdrop-blur-md`} onClick={onClose}><X size={18} /></button>
+        </div>
+        <div className="relative mx-auto mt-12 shrink-0 max-w-[calc(100vw-96px)]"
+          style={{ width: viewport.width - 96, height: displayHeight }}>
+          <div ref={scrollRef} className="h-full overflow-auto">
+          <div className="grid min-h-full min-w-full w-max place-items-center">
+            {errorId === screenshot.id ? (
+              <p role="alert" className="p-4 text-center text-white/70">Could not load the original screenshot.</p>
+            ) : image ? (
+              <div ref={imageElementRef} key={image.id} className="screenshot-viewer-image-in relative" style={{ animationName: direction > 0 ? 'screenshot-slide-from-right' : 'screenshot-slide-from-left' }}>
+              <img src={image.url} alt={`Screenshot ${screenshots.findIndex(shot => shot.id === image.id) + 1} of ${screenshots.length}`}
+                onClick={event => event.stopPropagation()} onError={() => setErrorId(screenshot.id)} draggable={false}
+                style={{ width: image.width * scale, height: image.height * scale }}
+                className="block max-w-none rounded-xl shadow-2xl" />
+              {editing && <ScreenshotDrawing id={image.id} url={image.url} width={image.width} height={image.height}
+                toolbarHost={drawingToolbarHost} onClose={() => setEditing(false)}
+                onSaved={saved => onSaved(saved)} />}
+              </div>
+            ) : <p role="status" className="p-4 text-center text-white/70">Loading screenshot...</p>}
+          </div>
+        </div>
+        </div>
+        <div className="flex h-20 shrink-0 items-center justify-center gap-3">
+          <div className="flex items-center gap-1 rounded-full bg-neutral-800/80 p-1 shadow-lg backdrop-blur-md" onClick={event => event.stopPropagation()}>
+            <button type="button" aria-label="Previous screenshot" title="Previous screenshot (Left arrow)"
+              className={controlClass} disabled={screenshots.length < 2 || editing}
+              onClick={() => { setDirection(-1); setIndex(current => (current - 1 + screenshots.length) % screenshots.length) }}><CaretLeft size={18} /></button>
+            <span className="min-w-10 text-center text-xs text-white/80" aria-live="polite">{index + 1} / {screenshots.length}</span>
+            <button type="button" aria-label="Next screenshot" title="Next screenshot (Right arrow)"
+              className={controlClass} disabled={screenshots.length < 2 || editing}
+              onClick={() => { setDirection(1); setIndex(current => (current + 1) % screenshots.length) }}><CaretRight size={18} /></button>
+          </div>
+          <div className="flex items-center gap-1 rounded-full bg-neutral-800/80 p-1 shadow-lg backdrop-blur-md" onClick={event => event.stopPropagation()}>
+            <button type="button" aria-label="Zoom out" className={controlClass} disabled={scale <= 0.05}
+              onClick={() => setZoom(Math.max(0.05, scale / 1.2))}><Minus size={16} /></button>
+            <button type="button" aria-label="Fit screenshot" title="Fit to window" onClick={() => setZoom(null)}
+              className="min-w-14 rounded-full py-2 text-center text-xs text-white/90 hover:bg-white/10">{Math.round(scale * 100)}%</button>
+            <button type="button" aria-label="Zoom in" className={controlClass} disabled={scale >= 4}
+              onClick={() => setZoom(Math.min(4, scale * 1.2))}><Plus size={16} /></button>
+          </div>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  )
+}
 
 export function RecentScreenshotButton({ expandDown = false }: { expandDown?: boolean }) {
   const [screenshots, setScreenshots] = useState<RecentScreenshot[]>([])
   const [dismissed, setDismissed] = useState<string[]>([])
   const [expanded, setExpanded] = useState(false)
   const [hoveredId, setHoveredId] = useState<string | null>(null)
+  const [viewer, setViewer] = useState<{ screenshots: RecentScreenshot[]; initialIndex: number } | null>(null)
+  const dragged = useRef(false)
 
   useEffect(() => {
     // Renderer hot reload can run against an older preload bridge until restart.
@@ -34,8 +195,9 @@ export function RecentScreenshotButton({ expandDown = false }: { expandDown?: bo
   }, [])
 
   const visible = screenshots.filter(screenshot => !dismissed.includes(screenshot.id))
-  if (!visible.length) return null
+  if (!visible.length && !viewer) return null
   return (
+    <>
     <div
       className="relative w-10 transition-[height] duration-200 ease-out motion-reduce:transition-none"
       style={{ height: expanded ? 40 + (visible.length - 1) * 52 : 40 }}
@@ -54,13 +216,22 @@ export function RecentScreenshotButton({ expandDown = false }: { expandDown?: bo
             transform: `rotate(${hoveredId === screenshot.id ? 8 : 3}deg) scale(${hoveredId === screenshot.id ? 1.05 : expanded ? 1 : 1 - index * 0.04})`,
           }}
         >
-          <Tooltip label="Drag screenshot to a panel" placement="left">
+          <Tooltip label="Click to view or drag screenshot to a panel" placement="left">
             <button
               type="button"
-              aria-label="Drag screenshot to a panel"
+              aria-label="Open screenshot preview"
               className="block h-10 w-10 cursor-grab overflow-hidden rounded-lg border-0 bg-transparent p-0 ring-1 ring-[var(--border-strong)] transition-[transform,filter] duration-200 ease-out group-hover:brightness-110 active:scale-95 active:cursor-grabbing motion-reduce:transition-none focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2"
               draggable
+              onPointerDown={() => { dragged.current = false }}
+              onKeyDown={event => {
+                if (event.key === 'Enter' || event.key === ' ') dragged.current = false
+              }}
+              onClick={() => {
+                if (dragged.current) return
+                setViewer({ screenshots: visible, initialIndex: index })
+              }}
               onDragStart={event => {
+                dragged.current = true
                 event.preventDefault()
                 void window.electronAPI.dragRecentScreenshot(screenshot.id).catch(() => {
                   // Keep the shortcut available if the native drag could not start.
@@ -68,9 +239,12 @@ export function RecentScreenshotButton({ expandDown = false }: { expandDown?: bo
               }}
             >
               <img src={screenshot.dataUrl} alt="Recent screenshot" draggable={false}
-                className="h-full w-full object-cover" />
+                className="h-full w-full object-contain" />
             </button>
           </Tooltip>
+          {screenshot.annotated && <span aria-label="Annotated screenshot" className="pointer-events-none absolute right-0.5 top-0.5 flex h-3.5 w-3.5 items-center justify-center rounded-full bg-black/75 text-white shadow-sm group-hover:opacity-0 group-focus-within:opacity-0">
+            <PencilSimple size={9} weight="bold" />
+          </span>}
           <button
             type="button"
             aria-label="Dismiss screenshot preview"
@@ -82,5 +256,10 @@ export function RecentScreenshotButton({ expandDown = false }: { expandDown?: bo
         </div>
       ))}
     </div>
+    {viewer && <ScreenshotViewer {...viewer} onClose={() => setViewer(null)} onSaved={saved => {
+      setScreenshots(current => [saved, ...current.filter(shot => shot.id !== saved.id)].slice(0, 5))
+      setViewer(null)
+    }} />}
+    </>
   )
 }
diff --git a/src/renderer/canvas/ScreenshotDrawing.tsx b/src/renderer/canvas/ScreenshotDrawing.tsx
new file mode 100644
index 00000000..620055f7
--- /dev/null
+++ b/src/renderer/canvas/ScreenshotDrawing.tsx
@@ -0,0 +1,112 @@
+import { useRef, useState, type PointerEvent } from 'react'
+import type { RecentScreenshot } from '../../shared/recentScreenshot'
+import { createPortal } from 'react-dom'
+import { ArrowCounterClockwise, DownloadSimple } from '@phosphor-icons/react'
+
+type Point = { x: number; y: number }
+type Stroke = { color: string; width: number; points: Point[] }
+
+export function ScreenshotDrawing({ id, url, width, height, toolbarHost, onClose, onSaved }: {
+  id: string; url: string; width: number; height: number; toolbarHost: HTMLElement | null; onClose: () => void; onSaved: (screenshot: RecentScreenshot, url: string) => void
+}) {
+  const [strokes, setStrokes] = useState<Stroke[]>([])
+  const [color, setColor] = useState('#ff453a')
+  const [brush, setBrush] = useState(4)
+  const [saving, setSaving] = useState(false)
+  const [message, setMessage] = useState('')
+  const activePointer = useRef<number | null>(null)
+  const point = (event: PointerEvent<SVGSVGElement>): Point => {
+    const bounds = event.currentTarget.getBoundingClientRect()
+    return {
+      x: Math.max(0, Math.min(width, (event.clientX - bounds.left) * width / bounds.width)),
+      y: Math.max(0, Math.min(height, (event.clientY - bounds.top) * height / bounds.height)),
+    }
+  }
+  const save = async () => {
+    setSaving(true)
+    setMessage('')
+    try {
+      const original = new Image()
+      original.src = url
+      await original.decode()
+      const canvas = document.createElement('canvas')
+      canvas.width = width
+      canvas.height = height
+      const context = canvas.getContext('2d')
+      if (!context) throw new Error('Drawing is unavailable.')
+      context.drawImage(original, 0, 0, width, height)
+      context.lineCap = 'round'
+      context.lineJoin = 'round'
+      for (const stroke of strokes) {
+        context.strokeStyle = stroke.color
+        context.lineWidth = stroke.width
+        context.beginPath()
+        context.moveTo(stroke.points[0].x, stroke.points[0].y)
+        for (const p of stroke.points.slice(1)) context.lineTo(p.x, p.y)
+        context.stroke()
+      }
+      const dataUrl = canvas.toDataURL('image/png')
+      if (typeof window.electronAPI.saveRecentScreenshot !== 'function') {
+        setMessage('Restart Cate to enable saving to the screenshot stack. Your drawing is still here.')
+        return
+      }
+      const saved = await window.electronAPI.saveRecentScreenshot(id, dataUrl)
+      onSaved(saved, dataUrl)
+    } catch (error) {
+      console.error('Could not save annotated screenshot', error)
+      setMessage('Could not save. Your drawing is still here; try again.')
+    } finally {
+      setSaving(false)
+    }
+  }
+  const buttonClass = 'flex h-8 shrink-0 items-center justify-center gap-1.5 rounded-full px-3 text-xs font-medium text-white/80 transition-colors hover:bg-white/10 hover:text-white disabled:opacity-30 focus-visible:outline focus-visible:outline-2 focus-visible:outline-white'
+  return <>
+    <svg viewBox={`0 0 ${width} ${height}`} aria-label="Draw on screenshot"
+      className="absolute inset-0 h-full w-full touch-none cursor-crosshair rounded-xl"
+      onClick={event => event.stopPropagation()}
+      onPointerDown={event => {
+        if (event.button !== 0 || saving || activePointer.current !== null) return
+        event.preventDefault()
+        event.stopPropagation()
+        event.currentTarget.setPointerCapture(event.pointerId)
+        activePointer.current = event.pointerId
+        const p = point(event)
+        setMessage('')
+        setStrokes(current => [...current, { color, width: brush * height / 600, points: [p, { x: p.x + 0.01, y: p.y }] }])
+      }}
+      onPointerMove={event => {
+        if (activePointer.current !== event.pointerId) return
+        const p = point(event)
+        setStrokes(current => current.map((stroke, index) => index === current.length - 1 ? { ...stroke, points: [...stroke.points, p] } : stroke))
+      }}
+      onPointerUp={event => { if (activePointer.current === event.pointerId) activePointer.current = null }}
+      onPointerCancel={() => { activePointer.current = null }}
+      onLostPointerCapture={() => { activePointer.current = null }}>
+      {strokes.map((stroke, index) => <polyline key={index} points={stroke.points.map(p => `${p.x},${p.y}`).join(' ')}
+        fill="none" stroke={stroke.color} strokeWidth={stroke.width} strokeLinecap="round" strokeLinejoin="round" />)}
+    </svg>
+    {toolbarHost && createPortal(
+    <div role="toolbar" aria-label="Screenshot drawing tools" className="titlebar-no-drag flex max-w-[calc(100vw-160px)] flex-wrap items-center justify-center gap-2 rounded-2xl border border-white/10 bg-neutral-800/90 px-3 py-2 shadow-xl backdrop-blur-md"
+      onClick={event => event.stopPropagation()} onPointerDown={event => event.stopPropagation()}>
+      <div className="flex items-center gap-2" aria-label="Pen colors">
+        {['#ff453a', '#ffcc00', '#30d158', '#0a84ff', '#ffffff'].map(value => <button key={value} type="button"
+          aria-label={`Pen color ${value}`} aria-pressed={color === value} onClick={() => setColor(value)}
+          className={`h-5 w-5 rounded-full border border-white/20 transition-shadow ${color === value ? 'ring-2 ring-white ring-offset-2 ring-offset-neutral-800' : 'hover:ring-2 hover:ring-white/40'}`}
+          style={{ backgroundColor: value }} />)}
+      </div>
+      <span className="mx-1 h-5 w-px bg-white/10" />
+      <div className="flex items-center gap-0.5" aria-label="Pen thickness">
+        {[2, 4, 8].map(value => <button key={value} type="button" aria-label={`Pen thickness ${value}`} aria-pressed={brush === value}
+          className={`flex h-8 w-8 items-center justify-center rounded-full ${brush === value ? 'bg-white/15' : 'hover:bg-white/10'}`}
+          onClick={() => setBrush(value)}><span className="rounded-full bg-white" style={{ width: value + 2, height: value + 2 }} /></button>)}
+      </div>
+      <button type="button" aria-label="Undo drawing" title="Undo last stroke" className={buttonClass} disabled={!strokes.length || saving}
+        onClick={() => setStrokes(current => current.slice(0, -1))}><ArrowCounterClockwise size={17} /></button>
+      <span className="h-5 w-px bg-white/10" />
+      <button type="button" className={buttonClass} disabled={saving} onClick={onClose}>Cancel</button>
+      <button type="button" className="flex h-8 items-center gap-1.5 rounded-full bg-white px-3 text-xs font-semibold text-neutral-900 transition-colors hover:bg-white/90 disabled:opacity-35"
+        disabled={!strokes.length || saving} onClick={() => { void save() }}><DownloadSimple size={15} />{saving ? 'Saving...' : 'Save'}</button>
+      {message && <span role="status" className="absolute left-1/2 top-full mt-2 w-max max-w-[80vw] -translate-x-1/2 rounded-lg bg-neutral-800 px-3 py-2 text-sm text-white">{message}</span>}
+    </div>, toolbarHost)}
+  </>
+}
diff --git a/src/renderer/canvas/useCanvasNodeStyle.ts b/src/renderer/canvas/useCanvasNodeStyle.ts
index ea4cc489..944121c3 100644
--- a/src/renderer/canvas/useCanvasNodeStyle.ts
+++ b/src/renderer/canvas/useCanvasNodeStyle.ts
@@ -116,7 +116,7 @@ export function useCanvasNodeStyle(args: StyleArgs) {
       pointerEvents: isExiting || isWholeNodeDragSource ? 'none' : undefined,
       userSelect: 'none',
       ...(isMaximized(node) ? {
-        position: 'fixed', left: 0, top: 0, width: '100vw', height: '100vh',
+        position: 'absolute', left: 0, top: 0, width: '100%', height: '100%',
         zIndex: 50, borderRadius: 0, border: 'none', boxShadow: 'none',
         transform: 'none', transition: 'none', filter: 'none',
         opacity: isExiting || isWholeNodeDragSource ? 0 : 1,
diff --git a/src/renderer/dialogs/SkillsDialog.tsx b/src/renderer/dialogs/SkillsDialog.tsx
index 76fdf1f0..78b63f71 100644
--- a/src/renderer/dialogs/SkillsDialog.tsx
+++ b/src/renderer/dialogs/SkillsDialog.tsx
@@ -34,6 +34,7 @@ import { LoadingState, Spinner } from '../ui/Spinner'
 import { PaletteTextInput } from '../ui/PaletteTextInput'
 import { InlineNotice } from '../ui/InlineNotice'
 import { IconButton } from '../ui/Button'
+import { POPOVER_SURFACE } from '../ui/Popover'
 import {
   SKILL_TARGETS,
   type InstalledSkill,
@@ -639,11 +640,11 @@ function AgentMenu({
   return createPortal(
     <div
       ref={rootRef}
-      className="fixed z-[1000] w-[200px] rounded-lg border border-subtle bg-surface-3 shadow-xl py-1 text-xs"
+      className={`fixed z-[1000] w-[200px] ${POPOVER_SURFACE} p-1.5 text-xs`}
       style={{ top: anchor.top, left: anchor.left }}
       onMouseDown={(e) => e.stopPropagation()}
     >
-      <div className="px-2.5 pt-0.5 pb-1 text-[10px] uppercase tracking-wide text-muted select-none">Install for</div>
+      <div className="px-2.5 pt-0.5 pb-1 text-[11px] font-medium text-muted select-none">Install for</div>
       {SKILL_TARGETS.map((t) => {
         const on = installedKeys.has(`${entry.id}:${t.id}`)
         const working = busy === t.id
@@ -652,7 +653,7 @@ function AgentMenu({
             key={t.id}
             onClick={() => void toggle(t.id)}
             disabled={working}
-            className="w-full flex items-center gap-2 px-2.5 py-1.5 text-left text-secondary hover:bg-surface-4 hover:text-primary disabled:opacity-50"
+            className="w-full flex items-center gap-2 rounded-lg px-2.5 py-1.5 text-left text-primary hover:bg-hover focus-visible:bg-hover disabled:opacity-50"
             title={on ? 'Uninstall skill' : 'Install skill'}
           >
             <span className="w-3.5 shrink-0 flex items-center justify-center text-accent">
diff --git a/src/renderer/docking/DockResizeHandle.tsx b/src/renderer/docking/DockResizeHandle.tsx
index 6ca2c855..f138f0b0 100644
--- a/src/renderer/docking/DockResizeHandle.tsx
+++ b/src/renderer/docking/DockResizeHandle.tsx
@@ -4,6 +4,7 @@
 
 import React, { useCallback, useRef, useEffect } from 'react'
 import { pinDocumentCursor } from '../lib/dom/pinDocumentCursor'
+import { SPLIT_DIVIDER_SIZE } from './splitSizing'
 
 interface DockResizeHandleProps {
   direction: 'horizontal' | 'vertical' // horizontal = left/right drag, vertical = up/down drag
@@ -101,18 +102,17 @@ export default function DockResizeHandle({ direction, onResize, onDoubleClick }:
     <div
       className={`
         flex-shrink-0 relative z-30 group pointer-events-auto
-        ${isHorizontal ? 'w-[5px] cursor-col-resize' : 'h-[5px] cursor-row-resize'}
+        ${isHorizontal ? 'cursor-col-resize' : 'cursor-row-resize'}
       `}
       onMouseDown={handleMouseDown}
       onDoubleClick={onDoubleClick}
-      style={{ WebkitAppRegion: 'no-drag' } as React.CSSProperties}
+      style={{ WebkitAppRegion: 'no-drag', [isHorizontal ? 'width' : 'height']: SPLIT_DIVIDER_SIZE } as React.CSSProperties}
     >
-      <div className={`absolute ${isHorizontal ? 'inset-y-0 -left-1 -right-1' : 'inset-x-0 -top-1 -bottom-1'}`} />
-      {/* Visible indicator on hover */}
+      <div className={`absolute ${isHorizontal ? 'inset-y-0 -left-[6px] -right-[6px]' : 'inset-x-0 -top-[6px] -bottom-[6px]'}`} />
+      {/* Fill the layout width so pane content meets the divider. */}
       <div
         className={`
-          absolute bg-surface-6 group-hover:bg-surface-6 transition-colors duration-150
-          ${isHorizontal ? 'inset-y-0 left-[2px] right-[2px]' : 'inset-x-0 top-[2px] bottom-[2px]'}
+          absolute inset-0 bg-surface-6 group-hover:bg-surface-6 transition-colors duration-150
         `}
       />
     </div>
diff --git a/src/renderer/docking/DockSplitContainer.drag.test.tsx b/src/renderer/docking/DockSplitContainer.drag.test.tsx
index e23fbc31..f4d1e9a0 100644
--- a/src/renderer/docking/DockSplitContainer.drag.test.tsx
+++ b/src/renderer/docking/DockSplitContainer.drag.test.tsx
@@ -17,10 +17,10 @@ it('starts resizing at the visible divider when saved ratios were constrained by
     Object.defineProperty(host.firstElementChild!, 'offsetWidth', { value: 1000 })
     const panes = host.querySelectorAll('[data-dock-pane]')
     Object.defineProperty(panes[0], 'offsetWidth', { value: 320 })
-    Object.defineProperty(panes[1], 'offsetWidth', { value: 675 })
+    Object.defineProperty(panes[1], 'offsetWidth', { value: 679 })
     act(() => host.querySelector('.cursor-col-resize')!.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, clientX: 320 })))
     act(() => document.dispatchEvent(new MouseEvent('mousemove', { clientX: 370 })))
-    expect((store.getState().zones.center.layout as DockSplitNode).ratios[0]).toBeCloseTo(370 / 995)
+    expect((store.getState().zones.center.layout as DockSplitNode).ratios[0]).toBeCloseTo(370 / 999)
   } finally {
     act(() => document.dispatchEvent(new MouseEvent('mouseup')))
     act(() => root.unmount())
@@ -47,9 +47,9 @@ it('can drag away from the minimum and reverse direction during the same gesture
     const handle = host.querySelector('.cursor-col-resize')!
     act(() => handle.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, clientX: 400 })))
     act(() => document.dispatchEvent(new MouseEvent('mousemove', { clientX: 500 })))
-    expect((store.getState().zones.center.layout as DockSplitNode).ratios[0]).toBeCloseTo(0.4 + 100 / 995)
+    expect((store.getState().zones.center.layout as DockSplitNode).ratios[0]).toBeCloseTo(0.4 + 100 / 999)
     act(() => document.dispatchEvent(new MouseEvent('mousemove', { clientX: 450 })))
-    expect((store.getState().zones.center.layout as DockSplitNode).ratios[0]).toBeCloseTo(0.4 + 50 / 995)
+    expect((store.getState().zones.center.layout as DockSplitNode).ratios[0]).toBeCloseTo(0.4 + 50 / 999)
   } finally {
     act(() => document.dispatchEvent(new MouseEvent('mouseup')))
     act(() => root.unmount())
diff --git a/src/renderer/docking/DockSplitContainer.test.ts b/src/renderer/docking/DockSplitContainer.test.ts
index b59a7931..56f91058 100644
--- a/src/renderer/docking/DockSplitContainer.test.ts
+++ b/src/renderer/docking/DockSplitContainer.test.ts
@@ -22,15 +22,15 @@ describe('clampSplitDelta', () => {
       { type: 'tabs', id: 'editor-stack', panelIds: ['editor'], activeIndex: 0 },
     ] }
     expect(clampSplitDelta(split, 0, -0.15, 1000, panelType)).toBeCloseTo(-0.15)
-    expect(clampSplitDelta(split, 0, -0.4, 1000, panelType)).toBeCloseTo(320 / 995 - 0.5)
+    expect(clampSplitDelta(split, 0, -0.4, 1000, panelType)).toBeCloseTo(320 / 999 - 0.5)
   })
   it('keeps a canvas at least its minimum wide in a horizontal split', () => {
-    expect(clampSplitDelta(horizontalSplit, 0, -0.4, 2000, panelType)).toBeCloseTo(PANEL_MINIMUM_SIZES.canvas.width / 1995 - 0.5)
+    expect(clampSplitDelta(horizontalSplit, 0, -0.4, 2000, panelType)).toBeCloseTo(PANEL_MINIMUM_SIZES.canvas.width / 1999 - 0.5)
   })
 
   it('keeps a canvas at least its minimum tall in a vertical split', () => {
     const verticalSplit = { ...horizontalSplit, direction: 'vertical' as const }
-    expect(clampSplitDelta(verticalSplit, 0, -0.4, 2000, panelType)).toBeCloseTo(PANEL_MINIMUM_SIZES.canvas.height / 1995 - 0.5)
+    expect(clampSplitDelta(verticalSplit, 0, -0.4, 2000, panelType)).toBeCloseTo(PANEL_MINIMUM_SIZES.canvas.height / 1999 - 0.5)
   })
 
   it('does not shrink panes further when their minimums cannot fit', () => {
diff --git a/src/renderer/docking/DockTabContextMenu.tsx b/src/renderer/docking/DockTabContextMenu.tsx
index eb26bb33..d2641ebd 100644
--- a/src/renderer/docking/DockTabContextMenu.tsx
+++ b/src/renderer/docking/DockTabContextMenu.tsx
@@ -5,6 +5,7 @@ import { createPortal } from 'react-dom'
 import type { PanelType } from '../../shared/types'
 import { SPLIT_MENU_PANEL_TYPES } from '../../shared/panels'
 import { PANEL_REGISTRY } from '../panels/registry'
+import { POPOVER_SURFACE } from '../ui/Popover'
 
 export type SplitMenuItem = { type: PanelType; label: string; Icon: React.ComponentType<any> }
 
@@ -49,7 +50,7 @@ export function DockTabContextMenu({ open, position, items, onPick, onClose, anc
       ref={menuRef}
       role="menu"
       aria-label="New Tab"
-      className="dock-new-tab-menu pointer-events-auto z-[1000] w-[220px] max-w-[calc(100vw-16px)] overflow-y-auto rounded-2xl border border-subtle bg-surface-3 shadow-lg p-1.5 text-[13px]"
+      className={`dock-new-tab-menu pointer-events-auto z-[1000] w-[220px] max-w-[calc(100vw-16px)] overflow-y-auto ${POPOVER_SURFACE} p-1.5 text-[13px]`}
       onKeyDown={(event) => {
         if (event.key === 'Escape' || event.key === 'Tab') { onClose(); event.stopPropagation(); return }
         if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return
diff --git a/src/renderer/docking/splitSizing.test.ts b/src/renderer/docking/splitSizing.test.ts
index 11a0e580..35a2d6eb 100644
--- a/src/renderer/docking/splitSizing.test.ts
+++ b/src/renderer/docking/splitSizing.test.ts
@@ -6,18 +6,18 @@ const pane = (id: string): DockLayoutNode => ({ id, type: 'tabs', panelIds: [id]
 it('allows a diff panel in a standard narrow dock without expanding its layout', () => {
   expect(layoutMinimum(pane('review'), () => 'review')).toEqual({ width: 320, height: 220 })
   expect(layoutMinimum({ id: 'row', type: 'split', direction: 'horizontal', ratios: [0.5, 0.5], children: [pane('review'), pane('terminal')] },
-    id => id as 'review' | 'terminal')).toEqual({ width: 645, height: 220 })
+    id => id as 'review' | 'terminal')).toEqual({ width: 641, height: 220 })
 })
 it('requires enough room for two usable panes and the divider', () => {
-  expect(canSplitPane(644, 400)).toBe(false)
-  expect(canSplitPane(645, 220)).toBe(true)
+  expect(canSplitPane(640, 400)).toBe(false)
+  expect(canSplitPane(641, 220)).toBe(true)
   expect(canSplitPane(1000, 219)).toBe(false)
 })
 it('uses physical pane minimums without inflating the dock to preserve uneven ratios', () => {
   const layout: DockLayoutNode = { id: 'row', type: 'split', direction: 'horizontal', ratios: [0.25, 0.75], children: [pane('a'), {
     id: 'column', type: 'split', direction: 'vertical', ratios: [0.5, 0.5], children: [pane('b'), pane('c')],
   }] }
-  expect(layoutMinimum(layout)).toEqual({ width: 645, height: 445 })
+  expect(layoutMinimum(layout)).toEqual({ width: 641, height: 441 })
   expect(layout.ratios).toEqual([0.25, 0.75])
 })
 
@@ -25,13 +25,13 @@ it('permits a third column based on the full row instead of requiring half the r
   const layout: DockLayoutNode = { id: 'row', type: 'split', direction: 'horizontal', ratios: [0.5, 0.5], children: [pane('a'), pane('b')] }
   expect(canSplitPane(500, 400)).toBe(false)
   expect(canSplitLayout(layout, 'b', 1000, 400)).toBe(true)
-  expect(canSplitLayout(layout, 'b', 969, 400)).toBe(false)
-  expect(canSplitLayout(layout, 'b', 970, 400)).toBe(true)
+  expect(canSplitLayout(layout, 'b', 961, 400)).toBe(false)
+  expect(canSplitLayout(layout, 'b', 962, 400)).toBe(true)
   expect(canSplitLayout(layout, 'missing', 1000, 400)).toBe(false)
 })
 
 it('keeps restored half/quarter/quarter layouts within the real three-pane minimum', () => {
-  expect(layoutMinimum({ id: 'row', type: 'split', direction: 'horizontal', ratios: [0.5, 0.25, 0.25], children: [pane('a'), pane('b'), pane('c')] })).toEqual({ width: 970, height: 220 })
+  expect(layoutMinimum({ id: 'row', type: 'split', direction: 'horizontal', ratios: [0.5, 0.25, 0.25], children: [pane('a'), pane('b'), pane('c')] })).toEqual({ width: 962, height: 220 })
 })
 
 it('honors every panel type minimum, including inactive tabs in a mixed stack', async () => {
diff --git a/src/renderer/docking/splitSizing.ts b/src/renderer/docking/splitSizing.ts
index c08101a0..8f50264d 100644
--- a/src/renderer/docking/splitSizing.ts
+++ b/src/renderer/docking/splitSizing.ts
@@ -1,6 +1,6 @@
 import { PANEL_MINIMUM_SIZES, type DockLayoutNode, type PanelType } from '../../shared/types'
 
-export const SPLIT_DIVIDER_SIZE = 5
+export const SPLIT_DIVIDER_SIZE = 1
 export const MIN_PANE_SIZE = { width: 320, height: 220 }
 
 export function layoutMinimum(node: DockLayoutNode, getPanelType?: (id: string) => PanelType | undefined): { width: number; height: number } {
diff --git a/src/renderer/hooks/useShortcuts.activeCanvas.test.tsx b/src/renderer/hooks/useShortcuts.activeCanvas.test.tsx
index 154082f7..c00886b9 100644
--- a/src/renderer/hooks/useShortcuts.activeCanvas.test.tsx
+++ b/src/renderer/hooks/useShortcuts.activeCanvas.test.tsx
@@ -151,7 +151,7 @@ describe('navigation from panel content', () => {
     expect(active.getState().selection).toEqual([left])
   })
 
-  it.each<PanelType>(['agent', 'browser', 'terminal', 'editor', 'canvas', 'document', 'review'])(
+  it.each<PanelType>(['agent', 'browser', 'terminal', 'editor', 'canvas', 'review'])(
     'supports chained jumps starting from a %s panel', (type) => {
       const left = active.getState().addNode('source', type, { x: 0, y: 0 })
       const middle = active.getState().addNode('middle', 'editor', { x: 2000, y: 0 })
diff --git a/src/renderer/lib/e2eHarness.ts b/src/renderer/lib/e2eHarness.ts
index 1565c011..df89e05c 100644
--- a/src/renderer/lib/e2eHarness.ts
+++ b/src/renderer/lib/e2eHarness.ts
@@ -559,7 +559,7 @@ export function installE2EHarness(): void {
     selectWorkspace,
     panelTypes,
     panels: () => Object.values(useAppStore.getState().getWorkspace(useAppStore.getState().selectedWorkspaceId)?.panels ?? {}),
-    createPanel: (type, filePath) => getPanelDef(type).create({ filePath, documentType: filePath ? 'image' : undefined, workspaceId: useAppStore.getState().selectedWorkspaceId, placement: { target: 'dock', zone: 'center' } })!,
+    createPanel: (type, filePath) => getPanelDef(type).create({ filePath, workspaceId: useAppStore.getState().selectedWorkspaceId, placement: { target: 'dock', zone: 'center' } })!,
     detachPanel: (id) => movePanelToNewWindow(useAppStore.getState().selectedWorkspaceId, id),
     openApplicationOverlay: (view, section) => {
       const ui = useUIStore.getState()
diff --git a/src/renderer/lib/editor/editorDocuments.ts b/src/renderer/lib/editor/editorDocuments.ts
index 3c985415..7302afb3 100644
--- a/src/renderer/lib/editor/editorDocuments.ts
+++ b/src/renderer/lib/editor/editorDocuments.ts
@@ -268,9 +268,9 @@ export class EditorDocument {
   dispose(): void { this.identityRevision++; this.watchEpoch++; this.stopWatching?.(); this.stopWatching = undefined; this.watchKey = undefined; this.listeners.clear() }
 }
 
-export function editorDocument(workspaceId: string, panelId: string, filePath?: string, rootPath?: string): EditorDocument {
+export function editorDocument(workspaceId: string, panelId: string, filePath?: string | null, rootPath?: string): EditorDocument {
   const panel = useAppStore.getState().workspaces.find(ws => ws.id === workspaceId)?.panels[panelId]
-  filePath ??= panel?.filePath
+  filePath = filePath === null ? undefined : filePath ?? panel?.filePath
   const previous = panelDocuments.get(panelId)
   if (previous && previous.filePathRef.current !== filePath) releaseEditorPanel(panelId)
   const key = keyFor(panelId, filePath)
@@ -339,7 +339,7 @@ export function applyFileEntryMove(event: FileEntryMoved): void {
   }
   const app = useAppStore.getState()
   const movedPanels = app.workspaces.flatMap(ws => Object.values(ws.panels).flatMap(panel => {
-    const path = (panel.type === 'editor' || panel.type === 'document') ? movedPath(panel.filePath) : undefined
+    const path = panel.type === 'editor' ? movedPath(panel.filePath) : undefined
     return path ? [{ workspaceId: ws.id, panel, path }] : []
   }))
   for (const [oldPath, document] of [...documents]) {
diff --git a/src/renderer/lib/editor/useFileSync.ts b/src/renderer/lib/editor/useFileSync.ts
index 6ed4403a..f030498e 100644
--- a/src/renderer/lib/editor/useFileSync.ts
+++ b/src/renderer/lib/editor/useFileSync.ts
@@ -6,7 +6,7 @@ export type { EditorConflict }
 export interface UseFileSyncParams {
   workspaceId: string
   panelId: string
-  filePath: string | undefined
+  filePath: string | null | undefined
   rootPath: string | undefined
   getModel: () => monaco.editor.ITextModel | null
   onExternalReplace?: (content: string) => void
diff --git a/src/renderer/lib/fs/fileRouting.ts b/src/renderer/lib/fs/fileRouting.ts
index 9d37ba6c..e1b6aaff 100644
--- a/src/renderer/lib/fs/fileRouting.ts
+++ b/src/renderer/lib/fs/fileRouting.ts
@@ -33,9 +33,5 @@ export function openFileAsPanel(
   placement?: PanelPlacement,
 ): string {
   const store = useAppStore.getState()
-  const docType = getDocumentType(filePath)
-  if (docType) {
-    return store.createDocument(workspaceId, filePath, docType, position, placement)
-  }
   return store.createEditor(workspaceId, filePath, position, placement)
 }
diff --git a/src/renderer/lib/panelTargetPicker.test.ts b/src/renderer/lib/panelTargetPicker.test.ts
index 99a32894..024e2cf4 100644
--- a/src/renderer/lib/panelTargetPicker.test.ts
+++ b/src/renderer/lib/panelTargetPicker.test.ts
@@ -56,7 +56,7 @@ describe.each(['main', 'detached'])('%s window target routing', (owner) => {
     vi.stubGlobal('window', { electronAPI: { showContextMenu: menu } })
   })
 
-  it.each(['terminal', 'agent', 'editor', 'browser', 'document', 'review'] as const)('creates %s directly in an entirely empty dock for every source', async (panelType) => {
+  it.each(['terminal', 'agent', 'editor', 'browser', 'review'] as const)('creates %s directly in an entirely empty dock for every source', async (panelType) => {
     for (const source of [{ source: 'overlay' as const }, {}, { sourcePanelId: 'closed-source' }]) {
       for (const availability of ['new', 'both', 'existing'] as const) {
         const result = await requestPanelTarget({ workspaceId, panelType, availability, ...source })
diff --git a/src/renderer/lib/workspace/sessionSerialize.ts b/src/renderer/lib/workspace/sessionSerialize.ts
index 970d3a45..60e2281b 100644
--- a/src/renderer/lib/workspace/sessionSerialize.ts
+++ b/src/renderer/lib/workspace/sessionSerialize.ts
@@ -36,7 +36,6 @@ const PASSTHROUGH_PANEL_FIELDS = [
   'tabs',
   'activeTabId',
   'proxyUrl',
-  'documentType',
   'sidebarView',
   'sidebarVisible',
 ] as const
diff --git a/src/renderer/lib/worktreeContext.test.ts b/src/renderer/lib/worktreeContext.test.ts
index 29689b73..5e1030af 100644
--- a/src/renderer/lib/worktreeContext.test.ts
+++ b/src/renderer/lib/worktreeContext.test.ts
@@ -29,7 +29,7 @@ describe('worktreeContext', () => {
       filePath: '/checkouts/feature/src/app.ts',
     }
     const document: PanelState = {
-      id: 'document', type: 'document', title: 'spec.pdf', isDirty: false,
+      id: 'document', type: 'editor', title: 'spec.pdf', isDirty: false,
       filePath: '/checkouts/feature/docs/spec.pdf',
     }
     const review: PanelState = {
diff --git a/src/renderer/lib/worktreeContext.ts b/src/renderer/lib/worktreeContext.ts
index ad9619d2..feb80321 100644
--- a/src/renderer/lib/worktreeContext.ts
+++ b/src/renderer/lib/worktreeContext.ts
@@ -46,7 +46,7 @@ export function worktreeForPanel<W extends WorktreePathLike>(
   const explicit = worktrees.find((worktree) => worktree.id === panel.worktreeId)
   if (explicit) return explicit
   if (panel.type === 'terminal' || panel.type === 'agent') return worktreeForPath(panel.cwd, worktrees)
-  if (panel.type === 'editor' || panel.type === 'document') {
+  if (panel.type === 'editor') {
     return worktreeForPath(panel.filePath, worktrees)
   }
   if (panel.type === 'review') return worktreeForPath(panel.reviewState?.repoPath, worktrees)
diff --git a/src/renderer/panels/AgentChangesView.tsx b/src/renderer/panels/AgentChangesView.tsx
index 09d1271c..3e9b3433 100644
--- a/src/renderer/panels/AgentChangesView.tsx
+++ b/src/renderer/panels/AgentChangesView.tsx
@@ -5,7 +5,7 @@ import { RecordedReviewButton } from './RecordedReviewButton'
 import { RecordedDiffHunk, type NoteDraft } from './ReviewDiff'
 import { ReviewDisplayOptions, ReviewFileFilter, ReviewRunStatus, ReviewStats, ToolbarButton } from './ReviewControls'
 import { getAgentLogoById } from '../lib/agent/agentLogos'
-import { PopoverSurface, useDismissableLayer, useViewportPopoverPosition } from '../ui/Popover'
+import { POPOVER_SURFACE, PopoverSurface, useDismissableLayer, useViewportPopoverPosition } from '../ui/Popover'
 import { AGENTS } from '../../shared/agents'
 import { filterAgentChanges } from '../../shared/agentChanges'
 import type { AgentChangedFile, AgentChangesFilter } from '../../shared/agentChanges'
@@ -119,7 +119,7 @@ function AgentChangesContent({ workspaceId, panelId, workspace, state }: PanelPr
         <ToolbarButton label={display.split ? 'Switch to unified diff' : 'Switch to split diff'} onClick={() => updateDisplay({ split: !display.split })}>{display.split ? <Rows size={14} /> : <SplitHorizontal size={14} />}</ToolbarButton>
         <div ref={morePopover} className="relative">
           <ToolbarButton label="More review options" active={moreOpen} onClick={() => setMoreOpen(!moreOpen)}><DotsThree size={16} /></ToolbarButton>
-          {moreOpen && <div role="menu" className="absolute right-0 top-8 z-50 w-56 rounded-xl border border-subtle bg-surface-2 p-1 shadow-xl"><ReviewDisplayOptions display={display} update={updateDisplay} /></div>}
+          {moreOpen && <div role="menu" className={`absolute right-0 top-8 z-50 w-56 ${POPOVER_SURFACE} p-1.5`}><ReviewDisplayOptions display={display} update={updateDisplay} /></div>}
         </div>
         <span className="text-muted" title="Recorded agent edits, not the current Git diff. Shell-generated or unreported edits may be missing. Counts are recorded edit totals."><Info size={14} aria-label="About recorded edits" /></span>
       </div>
diff --git a/src/renderer/panels/BrowserDownloadsPopover.tsx b/src/renderer/panels/BrowserDownloadsPopover.tsx
index d65ab61b..10e00f47 100644
--- a/src/renderer/panels/BrowserDownloadsPopover.tsx
+++ b/src/renderer/panels/BrowserDownloadsPopover.tsx
@@ -1,7 +1,7 @@
 import { useRef, type RefObject } from 'react'
 import { CircleCheck as CheckCircle, Download as DownloadSimple, FolderOpen, CircleAlert as WarningCircle, X } from 'lucide-react'
 import type { BrowserDownloadEntry } from '../../shared/types'
-import { useDismissableLayer } from '../ui/Popover'
+import { POPOVER_SURFACE, useDismissableLayer } from '../ui/Popover'
 
 export interface BrowserPanelDownload extends BrowserDownloadEntry {
   webContentsId: number
@@ -42,7 +42,7 @@ export function BrowserDownloadsPopover({ downloads, onAction, onClose, triggerR
     <div
       ref={ref}
       data-browser-downloads-popover
-      className="absolute right-2 top-[5.5rem] z-50 w-80 overflow-hidden rounded-xl border border-subtle bg-surface-2 shadow-2xl"
+      className={`absolute right-2 top-[5.5rem] z-50 w-80 overflow-hidden ${POPOVER_SURFACE}`}
       onMouseDown={(event) => event.stopPropagation()}
     >
       <div className="flex h-10 items-center border-b border-subtle px-3">
diff --git a/src/renderer/panels/BrowserMenu.tsx b/src/renderer/panels/BrowserMenu.tsx
index 22dd5e0d..bddd9fa2 100644
--- a/src/renderer/panels/BrowserMenu.tsx
+++ b/src/renderer/panels/BrowserMenu.tsx
@@ -7,7 +7,7 @@ import { useBrowserStore } from '../stores/browserStore'
 import { useUIStore } from '../stores/uiStore'
 import { BrowserFavicon } from './BrowserFavicon'
 import { faviconForUrl } from './browserUrl'
-import { useDismissableLayer } from '../ui/Popover'
+import { POPOVER_SURFACE, useDismissableLayer } from '../ui/Popover'
 
 interface Props {
   onNewTab: () => void
@@ -40,16 +40,16 @@ export function BrowserMenu({
 
   useDismissableLayer({ open: true, contentRef: ref, triggerRefs: [triggerRef], onDismiss: onClose })
 
-  const item = 'w-full flex items-center gap-2.5 px-3 h-8 text-sm text-secondary hover:bg-hover transition-colors text-left'
+  const item = 'w-full flex items-center gap-2.5 rounded-lg px-2.5 h-8 text-[13px] text-primary hover:bg-hover focus-visible:bg-hover transition-colors duration-100 motion-reduce:transition-none text-left'
 
   return (
     <div
       ref={ref}
-      className="absolute right-2 top-[5.5rem] z-40 w-56 rounded-lg border border-subtle bg-surface-2 shadow-2xl py-1"
+      className={`absolute right-2 top-[5.5rem] z-40 w-60 max-w-[calc(100%-16px)] ${POPOVER_SURFACE} p-1.5`}
       onMouseDown={(e) => e.stopPropagation()}
     >
       <button className={item} onClick={() => { onClose(); onNewTab() }}>
-        <Plus size={14} className="text-muted" /> New tab
+        <Plus size={16} className="shrink-0 text-secondary" /> New tab
       </button>
       <div
         className="relative"
@@ -67,7 +67,7 @@ export function BrowserMenu({
           aria-haspopup="menu"
           aria-expanded={bookmarksOpen}
         >
-          <BookmarkSimple size={14} className="text-muted" />
+          <BookmarkSimple size={16} className="shrink-0 text-secondary" />
           <span className="flex-1">Bookmarks</span>
           <CaretLeft size={12} className="text-muted" />
         </button>
@@ -75,7 +75,7 @@ export function BrowserMenu({
           <div
             role="menu"
             aria-label="Bookmarks"
-            className="absolute right-[calc(100%-4px)] top-0 z-50 max-h-80 w-64 overflow-y-auto rounded-lg border border-subtle bg-surface-2 py-1 shadow-2xl"
+            className={`absolute right-[calc(100%-4px)] top-0 z-50 max-h-80 w-64 overflow-y-auto ${POPOVER_SURFACE} p-1.5`}
           >
             {bookmarks.length === 0 ? (
               <div className="px-3 py-2 text-xs text-muted">No bookmarks yet</div>
@@ -84,7 +84,7 @@ export function BrowserMenu({
                 key={bookmark.url}
                 role="menuitem"
                 title={bookmark.url}
-                className="flex h-8 w-full items-center gap-2.5 px-3 text-left text-sm text-secondary transition-colors hover:bg-hover"
+                className={item}
                 onClick={() => {
                   onClose()
                   onNavigate(bookmark.url)
@@ -98,42 +98,44 @@ export function BrowserMenu({
         )}
       </div>
       <button className={item} onClick={() => { onClose(); onOpenHistory() }}>
-        <ClockCounterClockwise size={14} className="text-muted" /> History
+        <ClockCounterClockwise size={16} className="shrink-0 text-secondary" /> History
       </button>
       <button className={item} onClick={() => { onClose(); onOpenPasswordManager() }}>
-        <Key size={14} className="text-muted" /> Passwords and autofill
+        <Key size={16} className="shrink-0 text-secondary" /> Passwords and autofill
       </button>
-      <div className="my-1 border-t border-subtle" />
-      <div className="flex h-9 items-center gap-1 px-3 text-sm text-secondary">
+      <div className="mx-2.5 my-1.5 border-t border-subtle" />
+      <div className="flex h-9 items-center gap-3 px-2.5 text-[13px] text-primary">
         <span className="flex-1">Zoom</span>
-        <button
-          type="button"
-          onClick={onZoomOut}
-          disabled={zoomPercent <= 25}
-          className="flex h-7 w-7 items-center justify-center rounded-md text-secondary transition-colors hover:bg-hover hover:text-primary disabled:opacity-30"
-          aria-label="Zoom out"
-        >
-          <Minus size={13} />
-        </button>
-        <button
-          type="button"
-          onClick={onZoomReset}
-          className="h-7 min-w-12 rounded-md px-1 text-center text-xs tabular-nums text-secondary transition-colors hover:bg-hover hover:text-primary"
-          aria-label="Reset zoom"
-        >
-          {zoomPercent}%
-        </button>
-        <button
-          type="button"
-          onClick={onZoomIn}
-          disabled={zoomPercent >= 500}
-          className="flex h-7 w-7 items-center justify-center rounded-md text-secondary transition-colors hover:bg-hover hover:text-primary disabled:opacity-30"
-          aria-label="Zoom in"
-        >
-          <Plus size={13} />
-        </button>
+        <div className="flex h-7 items-center overflow-hidden rounded-lg border border-subtle bg-surface-4">
+          <button
+            type="button"
+            onClick={onZoomOut}
+            disabled={zoomPercent <= 25}
+            className="flex h-7 w-7 items-center justify-center text-secondary transition-colors hover:bg-hover hover:text-primary focus-visible:bg-hover disabled:opacity-30 disabled:hover:bg-transparent"
+            aria-label="Zoom out"
+          >
+            <Minus size={13} />
+          </button>
+          <button
+            type="button"
+            onClick={onZoomReset}
+            className="h-5 min-w-12 border-x border-subtle px-1.5 text-center text-xs tabular-nums text-primary transition-colors hover:bg-hover focus-visible:bg-hover"
+            aria-label="Reset zoom"
+          >
+            {zoomPercent}%
+          </button>
+          <button
+            type="button"
+            onClick={onZoomIn}
+            disabled={zoomPercent >= 500}
+            className="flex h-7 w-7 items-center justify-center text-secondary transition-colors hover:bg-hover hover:text-primary focus-visible:bg-hover disabled:opacity-30 disabled:hover:bg-transparent"
+            aria-label="Zoom in"
+          >
+            <Plus size={13} />
+          </button>
+        </div>
       </div>
-      <div className="my-1 border-t border-subtle" />
+      <div className="mx-2.5 my-1.5 border-t border-subtle" />
       <button
         className={item}
         onClick={() => {
@@ -141,7 +143,7 @@ export function BrowserMenu({
           useUIStore.getState().openSettings('browser')
         }}
       >
-        <Gear size={14} className="text-muted" /> Browser settings…
+        <Gear size={16} className="shrink-0 text-secondary" /> Browser settings…
       </button>
     </div>
   )
diff --git a/src/renderer/panels/BrowserPanel.tsx b/src/renderer/panels/BrowserPanel.tsx
index 9e95cd21..9b8fe695 100644
--- a/src/renderer/panels/BrowserPanel.tsx
+++ b/src/renderer/panels/BrowserPanel.tsx
@@ -32,6 +32,7 @@ import { Tooltip } from '../ui/Tooltip'
 import { Spinner } from '../ui/Spinner'
 import { PanelCenteredState } from '../ui/PanelCenteredState'
 import { Button } from '../ui/Button'
+import { POPOVER_SURFACE } from '../ui/Popover'
 import { useActivePanelStore } from '../lib/activePanel'
 import {
   BROWSER_HISTORY_URL,
@@ -1347,7 +1348,7 @@ export default function BrowserPanel({
             IPC; the selected password is decrypted and filled in main. */}
         {autofillPopup && (
           <div
-            className="absolute z-40 min-w-56 max-w-[calc(100%-1rem)] overflow-hidden rounded-lg border border-subtle bg-surface-2 shadow-2xl"
+            className={`absolute z-40 min-w-56 max-w-[calc(100%-1rem)] overflow-hidden ${POPOVER_SURFACE}`}
             style={{
               left: Math.max(
                 8,
diff --git a/src/renderer/panels/EditorPanel.navigation.test.tsx b/src/renderer/panels/EditorPanel.navigation.test.tsx
index fbc1d485..b8cc5e93 100644
--- a/src/renderer/panels/EditorPanel.navigation.test.tsx
+++ b/src/renderer/panels/EditorPanel.navigation.test.tsx
@@ -1,3 +1,4 @@
+vi.mock('./FilePreview', () => ({ default: () => <div data-testid="file-preview" /> }))
 import React, { act } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, expect, it, vi } from 'vitest'
@@ -206,12 +207,19 @@ it('protects edits to the next file after discarding the previous file', async (
   await act(async () => { await h.open!(['/test/third.ts']) })
   expect(window.electronAPI.confirmUnsavedChanges).toHaveBeenCalledTimes(2)
 })
-it.each([['pdf', 'pdf'], ['docx', 'docx'], ['png', 'image']])('routes %s files to document panels', async (ext, documentType) => {
+it.each(['pdf', 'docx', 'png'])('previews %s in the current Files tab and returns to text', async (ext) => {
   await mount('/test/code.ts')
+  const editorCount = h.editors.length
   await act(async () => { await h.open!([`/test/document.${ext}`]) })
   const panels = Object.values(useAppStore.getState().getWorkspace('test')!.panels)
-  expect(panels).toEqual(expect.arrayContaining([expect.objectContaining({ type: 'document', documentType, filePath: `/test/document.${ext}` })]))
-  expect(panels.find(p => p.id === 'editor')!.filePath).toBe('/test/code.ts')
+  expect(panels).toHaveLength(1)
+  expect(panels[0]).toMatchObject({ type: 'editor', filePath: `/test/document.${ext}` })
+  expect(h.editors).toHaveLength(editorCount)
+  expect(window.electronAPI.fsReadFile).not.toHaveBeenCalledWith(`/test/document.${ext}`, 'test')
+  expect(host.querySelector('[data-testid="file-preview"]')).not.toBeNull()
+  await act(async () => { await h.open!(['/test/next.ts']) })
+  expect(h.editors).toHaveLength(editorCount + 1)
+  expect(host.querySelector('[data-testid="file-preview"]')).toBeNull()
 })
 it('opens every selected file, reusing the current editor for the first text file', async () => {
   await mount('/test/code.ts')
diff --git a/src/renderer/panels/EditorPanel.tsx b/src/renderer/panels/EditorPanel.tsx
index e053efa2..906203a3 100644
--- a/src/renderer/panels/EditorPanel.tsx
+++ b/src/renderer/panels/EditorPanel.tsx
@@ -5,7 +5,7 @@ import { panelSearchStore } from '../stores/panelSearchStores'
 // EditorPanel — Monaco Editor wrapper for CanvasIDE editor panels.
 // =============================================================================
 
-import { useEffect, useRef, useCallback, useState } from 'react'
+import { lazy, Suspense, useEffect, useRef, useCallback, useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import { Check, ChevronDown, ChevronLeft, ChevronRight, Copy, ExternalLink, FolderOpen, Folders, Github, PanelLeftClose, PanelLeftOpen, Search } from 'lucide-react'
 import { perfCount, useRenderCount } from '../lib/perf/perfClient'
@@ -242,6 +242,8 @@ function detectLanguage(filePath: string): string {
 // EditorPanel component
 // -----------------------------------------------------------------------------
 
+const FilePreview = lazy(() => import('./FilePreview'))
+
 export default function EditorPanel({
   panelId,
   workspaceId,
@@ -249,6 +251,7 @@ export default function EditorPanel({
   nodeId,
 }: EditorPanelProps) {
   useRenderCount('EditorPanel')
+  const previewType = filePath ? getDocumentType(filePath) : null
   const shortcutLabel = useShortcutLabel()
   const containerRef = useRef<HTMLDivElement>(null)
   const editorRef = useRef<monaco.editor.IStandaloneCodeEditor | null>(null)
@@ -384,7 +387,7 @@ export default function EditorPanel({
   const sync = useFileSync({
     workspaceId,
     panelId,
-    filePath,
+    filePath: previewType ? null : filePath,
     rootPath: checkoutRoot,
     getModel,
     onExternalReplace,
@@ -410,7 +413,7 @@ export default function EditorPanel({
       return
     }
     if (switchingFile.current) return
-    const nextPath = paths.find((path) => !getDocumentType(path))
+    const nextPath = paths[0]
     switchingFile.current = true
     try {
       const store = useAppStore.getState()
@@ -464,7 +467,7 @@ export default function EditorPanel({
   // ---------------------------------------------------------------------------
 
   useEffect(() => {
-    if (!containerRef.current) return
+    if (previewType || !containerRef.current) return
     setLoadError(null)
     setMarkdownContent('')
 
@@ -646,7 +649,7 @@ export default function EditorPanel({
       editorRef.current = null
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [filePath, workspaceId])
+  }, [filePath, workspaceId, previewType])
 
   // ---------------------------------------------------------------------------
   // Listen for save-file custom event
@@ -909,7 +912,8 @@ export default function EditorPanel({
       </NodePopover>}
       <div className="files-content flex-1 min-h-0 flex" style={{ backgroundColor: editorBackground, '--file-explorer-bg': editorBackground } as CSSProperties}>
       <div className={`${editorVisible ? 'flex-1' : 'hidden'} min-w-0 relative`}>
-        {showDiff && conflict?.kind === 'changed' && (
+        {previewType && filePath && <Suspense fallback={<LoadingState label="Loading preview…" className="h-full" />}><FilePreview key={filePath} filePath={filePath} workspaceId={workspaceId} /></Suspense>}
+        {!previewType && showDiff && conflict?.kind === 'changed' && (
           <div className="absolute inset-0 z-30 bg-surface-1">
             <div ref={diffOverlayRef} className="w-full h-full" />
           </div>
@@ -917,7 +921,7 @@ export default function EditorPanel({
         {markdownPreview && isMarkdown && (
           <MarkdownPreview content={markdownContent} />
         )}
-        {loadError && (
+        {!previewType && loadError && (
           <PanelCenteredState
             className="absolute inset-0 z-20 bg-surface-1 px-6"
             title={/ENOENT|no such file/i.test(loadError) ? 'File not found in this worktree' : 'Couldn’t open this file'}
@@ -926,10 +930,10 @@ export default function EditorPanel({
               : loadError}</span>}
           />
         )}
-        {fileLoading && (
+        {!previewType && fileLoading && (
           <LoadingState label="Loading file…" className="absolute inset-0 z-20 bg-surface-1 text-sm" />
         )}
-        <div ref={containerRef} className={`w-full h-full ${(markdownPreview && isMarkdown) || loadError ? 'hidden' : ''}`} />
+        <div ref={containerRef} className={`w-full h-full ${previewType || (markdownPreview && isMarkdown) || loadError ? 'hidden' : ''}`} />
 
       </div>
       {explorerRoot && (
diff --git a/src/renderer/panels/DocumentPanel.component.test.tsx b/src/renderer/panels/FilePreview.component.test.tsx
similarity index 92%
rename from src/renderer/panels/DocumentPanel.component.test.tsx
rename to src/renderer/panels/FilePreview.component.test.tsx
index caddeedb..d43b0eab 100644
--- a/src/renderer/panels/DocumentPanel.component.test.tsx
+++ b/src/renderer/panels/FilePreview.component.test.tsx
@@ -21,7 +21,7 @@ vi.mock('pdfjs-dist', () => ({
   getDocument: pdfMocks.getDocument,
 }))
 
-import DocumentPanel from './DocumentPanel'
+import FilePreview from './FilePreview'
 import { useAppStore } from '../stores/appStore'
 import type { PanelState, WorkspaceState } from '../../shared/types'
 
@@ -32,7 +32,7 @@ let root: Root
 let fsReadBinary: ReturnType<typeof vi.fn>
 let shellShowInFolder: ReturnType<typeof vi.fn>
 
-function workspace(filePath?: string, documentType?: PanelState['documentType']): WorkspaceState {
+function workspace(filePath?: string, _documentType?: 'pdf' | 'docx' | 'image'): WorkspaceState {
   return {
     id: 'ws-1',
     name: 'Workspace',
@@ -41,18 +41,22 @@ function workspace(filePath?: string, documentType?: PanelState['documentType'])
     panels: {
       'document-1': {
         id: 'document-1',
-        type: 'document',
+        type: 'editor',
         title: 'Document',
         filePath,
-        documentType,
       } as PanelState,
     },
   }
 }
 
+function PreviewHarness() {
+  const filePath = useAppStore(s => s.workspaces[0].panels['document-1'].filePath)
+  return <FilePreview filePath={filePath ?? ''} workspaceId="ws-1" />
+}
+
 function mount(): void {
   act(() => {
-    root.render(<DocumentPanel panelId="document-1" workspaceId="ws-1" />)
+    root.render(<PreviewHarness />)
   })
 }
 
@@ -79,7 +83,7 @@ afterEach(() => {
   useAppStore.setState(initialAppState, true)
 })
 
-describe('DocumentPanel component', () => {
+describe('FilePreview component', () => {
   it('loads binary data for the owning workspace and trusts magic bytes over stale persisted type', async () => {
     useAppStore.setState({ workspaces: [workspace('/workspace/photo.png', 'pdf')], selectedWorkspaceId: 'ws-1' })
     fsReadBinary.mockResolvedValue(Uint8Array.from([0x89, 0x50, 0x4e, 0x47]).buffer)
diff --git a/src/renderer/panels/DocumentPanel.tsx b/src/renderer/panels/FilePreview.tsx
similarity index 96%
rename from src/renderer/panels/DocumentPanel.tsx
rename to src/renderer/panels/FilePreview.tsx
index 4e01e155..b044dd14 100644
--- a/src/renderer/panels/DocumentPanel.tsx
+++ b/src/renderer/panels/FilePreview.tsx
@@ -1,7 +1,6 @@
 import React, { useEffect, useRef, useState, useCallback, useMemo } from 'react'
 import * as pdfjsLib from 'pdfjs-dist'
-import type { PanelProps } from './types'
-import { useAppStore } from '../stores/appStore'
+import { getDocumentType } from '../lib/fs/fileRouting'
 import { ArrowLeft, ArrowRight, Minus, Plus } from 'lucide-react'
 import { errorMessage } from '../lib/errorMessage'
 import { viewedArrayBuffer } from './documentBytes'
@@ -302,14 +301,8 @@ function DocxViewer({ data }: { data: Uint8Array }) {
 // Main component
 // ---------------------------------------------------------------------------
 
-export default function DocumentPanel({ panelId, workspaceId }: PanelProps) {
-  const panelState = useAppStore((s) => {
-    const ws = s.workspaces.find((w) => w.id === workspaceId) ?? s.workspaces.find((w) => w.id === s.selectedWorkspaceId)
-    return ws?.panels[panelId]
-  })
-
-  const filePath = panelState?.filePath
-  const storeDocumentType = panelState?.documentType
+export default function FilePreview({ filePath, workspaceId }: { filePath: string; workspaceId: string }) {
+  const storeDocumentType = getDocumentType(filePath)
 
   const [data, setData] = useState<Uint8Array | null>(null)
   const [loading, setLoading] = useState(true)
diff --git a/src/renderer/panels/GitReviewPanel.lifecycle.test.tsx b/src/renderer/panels/GitReviewPanel.lifecycle.test.tsx
index 4bc2aa1a..0d0175c4 100644
--- a/src/renderer/panels/GitReviewPanel.lifecycle.test.tsx
+++ b/src/renderer/panels/GitReviewPanel.lifecycle.test.tsx
@@ -2,8 +2,8 @@ import React, { act } from 'react'
 import { createRoot } from 'react-dom/client'
 import { expect, it, vi } from 'vitest'
 
-const h = vi.hoisted(() => ({ createEditor: vi.fn(), createDocument: vi.fn(), workspace: { id: 'ws', rootPath: '/repo', panels: { review: { reviewState: { repoPath: '/repo', spec: { kind: 'uncommitted' }, display: {}, notes: [{ path: 'gone.ts', side: 'file', status: 'open' }] } as any } } } }))
-vi.mock('../stores/appStore', () => ({ useAppStore: Object.assign((selector: any) => selector({ workspaces: [h.workspace] }), { getState: () => ({ createEditor: h.createEditor, createDocument: h.createDocument, getWorkspace: () => h.workspace, setPanelReviewState: (_w: string, _p: string, next: any) => { h.workspace.panels.review.reviewState = next } }) }) }))
+const h = vi.hoisted(() => ({ createEditor: vi.fn(), workspace: { id: 'ws', rootPath: '/repo', panels: { review: { reviewState: { repoPath: '/repo', spec: { kind: 'uncommitted' }, display: {}, notes: [{ path: 'gone.ts', side: 'file', status: 'open' }] } as any } } } }))
+vi.mock('../stores/appStore', () => ({ useAppStore: Object.assign((selector: any) => selector({ workspaces: [h.workspace] }), { getState: () => ({ createEditor: h.createEditor, getWorkspace: () => h.workspace, setPanelReviewState: (_w: string, _p: string, next: any) => { h.workspace.panels.review.reviewState = next } }) }) }))
 vi.mock('../stores/gitStatusStore', () => ({ useGitStatusSnapshot: () => ({ revision: 0 }), gitStatusStore: {} }))
 vi.mock('../stores/useWorktrees', () => ({ useWorktrees: () => [] }))
 vi.mock('../lib/review/reviewAgent', () => ({}))
@@ -25,8 +25,8 @@ it('does not overwrite Agent changes when an unmounted Git comparison finishes',
   } finally { act(() => root.unmount()) }
 })
 
-it.each([['a.png', 'image'], ['a.pdf', 'pdf'], ['a.docx', 'docx']])('routes review file %s to its document surface', async (path, type) => {
-  h.createEditor.mockClear(); h.createDocument.mockClear()
+it.each(['a.png', 'a.pdf', 'a.docx'])('opens review file %s in Files', async (path) => {
+  h.createEditor.mockClear()
   h.workspace.panels.review.reviewState = { repoPath: '/repo', spec: { kind: 'uncommitted' }, display: {}, notes: [] }
   window.electronAPI = { gitCompare: async () => ({ files: [{ path, status: 'modified', additions: 0, deletions: 0 }], additions: 0, deletions: 0 }), gitBranchList: async () => ({ branches: [] }), gitLog: async () => [] } as any
   const host = document.createElement('div')
@@ -36,7 +36,6 @@ it.each([['a.png', 'image'], ['a.pdf', 'pdf'], ['a.docx', 'docx']])('routes revi
     const open = host.querySelector<HTMLButtonElement>('button[aria-label="Open file"]')!
     expect(open).not.toBeNull()
     await act(async () => open.click())
-    expect(h.createDocument).toHaveBeenCalledWith('ws', '/repo/' + path, type, undefined, { target: 'dock', zone: 'right', stackId: 'review-stack' })
-    expect(h.createEditor).not.toHaveBeenCalled()
+    expect(h.createEditor).toHaveBeenCalledWith('ws', '/repo/' + path, undefined, { target: 'dock', zone: 'right', stackId: 'review-stack' })
   } finally { act(() => root.unmount()) }
 })
diff --git a/src/renderer/panels/GitReviewPanel.tsx b/src/renderer/panels/GitReviewPanel.tsx
index 3e6ba997..1e54adcf 100644
--- a/src/renderer/panels/GitReviewPanel.tsx
+++ b/src/renderer/panels/GitReviewPanel.tsx
@@ -25,6 +25,7 @@ import { openFileAsPanel } from '../lib/fs/fileRouting'
 import { placementForPanel } from '../lib/workspace/canvasAccess'
 import { AgentPickerPopover, ReviewActionButton, ReviewDisplayOptions, ReviewFileFilter, ReviewMenuButton, ReviewRunStatus, ReviewStats, ToolbarButton, type AgentChoice } from './ReviewControls'
 import { HunkView, type NoteDraft } from './ReviewDiff'
+import { POPOVER_SURFACE } from '../ui/Popover'
 
 interface BranchInfo {
   name: string
@@ -890,7 +891,7 @@ export default function GitReviewPanel({ panelId, workspaceId }: PanelProps) {
           <div ref={moreMenuRef} className="relative">
             <ToolbarButton label="More review options" active={moreOpen} onClick={() => setMoreOpen((open) => !open)}><DotsThree size={16} /></ToolbarButton>
             {moreOpen && (
-              <div role="menu" className="absolute right-0 top-8 z-50 w-56 rounded-xl border border-subtle bg-surface-2 p-1 shadow-xl">
+              <div role="menu" className={`absolute right-0 top-8 z-50 w-56 ${POPOVER_SURFACE} p-1.5`}>
                 <ReviewDisplayOptions display={reviewState.display} update={updateDisplay} />
                 <ReviewMenuButton label="Load full files" active={reviewState.display.fullFile} onClick={() => { updateDisplay({ fullFile: !reviewState.display.fullFile }); setDiffs({}) }}><File size={14} /></ReviewMenuButton>
                 <ReviewMenuButton label="Image previews" active={reviewState.display.advancedPreview} onClick={() => updateDisplay({ advancedPreview: !reviewState.display.advancedPreview })}><ImageSquare size={14} /></ReviewMenuButton>
diff --git a/src/renderer/panels/PanelHost.test.tsx b/src/renderer/panels/PanelHost.test.tsx
index 3d58af7f..3fb8dd73 100644
--- a/src/renderer/panels/PanelHost.test.tsx
+++ b/src/renderer/panels/PanelHost.test.tsx
@@ -122,7 +122,7 @@ it('updates only changed leaf content without invalidating the canvas render cal
   expect(host.textContent).toBe('Changedb')
 })
 
-it.each(['canvas', 'terminal', 'editor', 'browser', 'agent', 'document', 'review', 'surface'] as const)('gates %s content before mounting without a workspace', (type) => {
+it.each(['canvas', 'terminal', 'editor', 'browser', 'agent', 'review', 'surface'] as const)('gates %s content before mounting without a workspace', (type) => {
   const mounted = vi.fn()
   function Content() { React.useEffect(mounted, []); return <span>Content</span> }
   registryMocks.renderPanelComponent.mockReturnValue(<Content />)
diff --git a/src/renderer/panels/ReviewControls.tsx b/src/renderer/panels/ReviewControls.tsx
index 5264221a..d568ccac 100644
--- a/src/renderer/panels/ReviewControls.tsx
+++ b/src/renderer/panels/ReviewControls.tsx
@@ -6,6 +6,7 @@ import { useAppStore } from '../stores/appStore'
 import { getAgentLogoById } from '../lib/agent/agentLogos'
 import { Tooltip } from '../ui/Tooltip'
 import { LoadingState, Spinner } from '../ui/Spinner'
+import { POPOVER_SURFACE } from '../ui/Popover'
 
 export interface AgentChoice { agent: AgentDef; ready: boolean }
 type AgentAction = { kind: 'review' | 'changes' }
@@ -120,7 +121,7 @@ export function AgentPickerPopover({
   onConfirm: () => void
 }) {
   return (
-    <div role="dialog" aria-label={action.kind === 'review' ? 'Choose terminal review CLI' : 'Choose terminal changes CLI'} className="absolute right-0 top-9 z-50 w-64 rounded-lg border border-subtle bg-surface-2 p-1.5 shadow-xl">
+    <div role="dialog" aria-label={action.kind === 'review' ? 'Choose terminal review CLI' : 'Choose terminal changes CLI'} className={`absolute right-0 top-9 z-50 w-64 ${POPOVER_SURFACE} p-1.5`}>
       <p className="px-1 pb-1.5 text-[10px] text-muted">
         {action.kind === 'review'
           ? 'Choose a terminal CLI to review this diff.'
diff --git a/src/renderer/panels/UrlSuggestions.tsx b/src/renderer/panels/UrlSuggestions.tsx
index ed423e81..6df571ec 100644
--- a/src/renderer/panels/UrlSuggestions.tsx
+++ b/src/renderer/panels/UrlSuggestions.tsx
@@ -3,6 +3,9 @@
 // presentational: the parent (BrowserPanel) owns the query + active selection.
 // =============================================================================
 import type { BrowserHistoryEntry } from '../../shared/types'
+import { POPOVER_SURFACE } from '../ui/Popover'
+import { BrowserFavicon } from './BrowserFavicon'
+import { faviconForUrl } from './browserUrl'
 
 interface Props {
   items: BrowserHistoryEntry[]
@@ -14,7 +17,7 @@ interface Props {
 export function UrlSuggestions({ items, activeIndex, onPick, onHover }: Props): JSX.Element | null {
   if (items.length === 0) return null
   return (
-    <div className="absolute left-0 right-0 top-full mt-1 z-30 rounded-lg border border-subtle bg-surface-5 shadow-2xl overflow-hidden">
+    <div className={`absolute left-0 right-0 top-full mt-1 z-30 ${POPOVER_SURFACE} overflow-hidden p-1.5`}>
       {items.map((item, i) => (
         <button
           key={item.url}
@@ -22,12 +25,16 @@ export function UrlSuggestions({ items, activeIndex, onPick, onHover }: Props):
           // hides the list; preventDefault keeps focus where it is.
           onMouseDown={(e) => { e.preventDefault(); onPick(item.url) }}
           onMouseEnter={() => onHover(i)}
-          className={`w-full flex items-center gap-2 px-3 py-1.5 text-left text-sm ${
+          className={`w-full flex items-center gap-2.5 rounded-lg px-2.5 h-9 text-left text-[13px] hover:bg-hover focus-visible:bg-hover transition-colors duration-100 motion-reduce:transition-none ${
             i === activeIndex ? 'bg-hover' : ''
           }`}
         >
-          <span className="text-primary truncate">{item.title || item.url}</span>
-          <span className="text-muted truncate ml-auto text-xs">{item.url}</span>
+          <BrowserFavicon src={faviconForUrl(item.url)} size={16} />
+          <span className="min-w-0 max-w-[60%] shrink-0 truncate text-primary">{item.title || item.url}</span>
+          <span className="min-w-0 truncate text-secondary">
+            <span aria-hidden="true">· </span>
+            {item.url.replace(/^https?:\/\/(?:www\.)?/, '').replace(/\/$/, '')}
+          </span>
         </button>
       ))}
     </div>
diff --git a/src/renderer/panels/documentBytes.ts b/src/renderer/panels/documentBytes.ts
index 5e5f1137..b0bb9d33 100644
--- a/src/renderer/panels/documentBytes.ts
+++ b/src/renderer/panels/documentBytes.ts
@@ -1,5 +1,5 @@
 // =============================================================================
-// Pure byte helpers for DocumentPanel sub-viewers. Kept out of the React module
+// Pure byte helpers for FilePreview viewers. Kept out of the React module
 // so they can be unit-tested without jsdom/pdfjs/mammoth.
 // =============================================================================
 
diff --git a/src/renderer/panels/registry.ts b/src/renderer/panels/registry.ts
index 787d4fa5..f83f8f8b 100644
--- a/src/renderer/panels/registry.ts
+++ b/src/renderer/panels/registry.ts
@@ -14,7 +14,7 @@ import { T3Logo } from '../ui/T3Logo'
 // =============================================================================
 
 import React, { type LazyExoticComponent, type ComponentType } from 'react'
-import { Terminal, Globe, Grid2X2 as SquaresFour, FileText as FileDoc, GitCompareArrows as GitDiff, type LucideIcon } from 'lucide-react'
+import { Terminal, Globe, Grid2X2 as SquaresFour, GitCompareArrows as GitDiff, type LucideIcon } from 'lucide-react'
 import { Folders, Plus } from 'lucide-react'
 import type { PanelType, Point, PanelState } from '../../shared/types'
 import type { PanelPlacement } from '../stores/appStore'
@@ -35,7 +35,6 @@ const EditorPanel = React.lazy(() => import('./EditorPanel'))
 const BrowserPanel = React.lazy(() => import('./BrowserPanel'))
 const CanvasPanel = React.lazy(() => import('./CanvasPanel'))
 const AgentPanel = React.lazy(() => import('./AgentPanel'))
-const DocumentPanel = React.lazy(() => import('./DocumentPanel'))
 const ReviewPanel = React.lazy(() => import('./ReviewPanel'))
 
 // -----------------------------------------------------------------------------
@@ -57,7 +56,6 @@ export interface PanelCreateArgs {
   /** Terminal only. */
   initialInput?: string
   /** Document only. */
-  documentType?: 'pdf' | 'docx' | 'image'
 }
 
 export interface RendererPanelDefinition extends SharedPanelDefinition {
@@ -159,14 +157,6 @@ export const PANEL_REGISTRY: Record<PanelType, RendererPanelDefinition> = {
       trackCreated('agent', useAppStore.getState().createAgent(workspaceId, canvasPoint, placement, cwd, worktreeId) || null),
     props: baseProps,
   },
-  document: {
-    ...PANEL_DEFINITIONS.document,
-    icon: FileDoc,
-    Component: DocumentPanel,
-    create: ({ workspaceId, canvasPoint, placement, filePath, documentType }) =>
-      trackCreated('document', useAppStore.getState().createDocument(workspaceId, filePath, documentType, canvasPoint, placement) || null),
-    props: (panel, ctx) => ({ ...baseProps(panel, ctx), filePath: panel.filePath }),
-  },
   review: {
     ...PANEL_DEFINITIONS.review,
     icon: GitDiff,
@@ -211,7 +201,7 @@ export function renderPanelComponent(
   panel: PanelState,
   ctx: PanelRenderContext,
 ): React.ReactElement | null {
-  const def = PANEL_REGISTRY[panel.type]
+  const def = getPanelDef(panel.type)
   if (!def) return null
   const { Component } = def
   const props = def.props(panel, ctx) as PanelProps & Record<string, unknown>
diff --git a/src/renderer/shells/DockWindowShell.tsx b/src/renderer/shells/DockWindowShell.tsx
index 66f74491..a6b81091 100644
--- a/src/renderer/shells/DockWindowShell.tsx
+++ b/src/renderer/shells/DockWindowShell.tsx
@@ -434,7 +434,7 @@ export default function DockWindowShell({ workspaceId: initialWorkspaceId }: Doc
           }
         `}</style>
         {/* Full content area — center zone only */}
-        <div className="flex-1 min-h-0 min-w-0 relative overflow-hidden">
+        <div data-panel-maximize-root className="flex-1 min-h-0 min-w-0 relative overflow-hidden">
           <DockZone
             position="center"
             renderPanel={renderPanel}
diff --git a/src/renderer/shells/MainWindowShell.tsx b/src/renderer/shells/MainWindowShell.tsx
index fa4fa10b..7fd7c80a 100644
--- a/src/renderer/shells/MainWindowShell.tsx
+++ b/src/renderer/shells/MainWindowShell.tsx
@@ -135,6 +135,7 @@ export default function MainWindowShell({
   return (
     <div
       ref={shellRef}
+      data-panel-maximize-root
       className="main-window-shell-root flex flex-col h-full w-full min-h-0 min-w-0 relative"
       style={workspaceAccent ? ({ ['--workspace-accent' as string]: workspaceAccent } as React.CSSProperties) : undefined}
     >
diff --git a/src/renderer/sidebar/FileExplorer.performance.test.tsx b/src/renderer/sidebar/FileExplorer.performance.test.tsx
index 456484ec..e0f76a65 100644
--- a/src/renderer/sidebar/FileExplorer.performance.test.tsx
+++ b/src/renderer/sidebar/FileExplorer.performance.test.tsx
@@ -22,7 +22,7 @@ it('expands through the shared queue, refreshes one directory, and navigates vir
   mocks.read.mockImplementation(async (path: string) => path === '/repo'
     ? [file('/repo/a', true), file('/repo/b', true)]
     : Array.from({ length: 1000 + (extra ? 1 : 0) }, (_, index) => file(`${path}/${index}.ts`)))
-  Object.assign(window, { electronAPI: { fsReadDir: mocks.read, onSettingsChanged: () => vi.fn() } })
+  Object.assign(window, { electronAPI: { fsReadDir: mocks.read, runtimeRetryLocal: vi.fn().mockResolvedValue({ ok: true }), onSettingsChanged: () => vi.fn() } })
   const host = document.createElement('div')
   document.body.append(host)
   const root = createRoot(host)
@@ -58,7 +58,7 @@ it('paints a warm expanded tree while revalidation is still pending', async () =
     return Promise.resolve(path === '/warm-a' ? [file('/warm-a/sub', true)]
       : path === '/warm-a/sub' ? [file('/warm-a/sub/leaf.ts')] : [file('/warm-b/other.ts')])
   })
-  Object.assign(window, { electronAPI: { fsReadDir: mocks.read, onSettingsChanged: () => vi.fn() } })
+  Object.assign(window, { electronAPI: { fsReadDir: mocks.read, runtimeRetryLocal: vi.fn().mockResolvedValue({ ok: true }), onSettingsChanged: () => vi.fn() } })
   const host = document.createElement('div')
   document.body.append(host)
   const root = createRoot(host)
@@ -77,3 +77,24 @@ it('paints a warm expanded tree while revalidation is still pending', async () =
     host.remove()
   }
 })
+
+it('shows read failures instead of an empty folder and recovers on retry', async () => {
+  vi.useFakeTimers()
+  mocks.watch.mockReturnValue(vi.fn())
+  mocks.read.mockRejectedValue(new Error('No runtime registered for id "local"'))
+  Object.assign(window, { electronAPI: { fsReadDir: mocks.read, runtimeRetryLocal: vi.fn().mockResolvedValue({ ok: true }), onSettingsChanged: () => vi.fn() } })
+  const host = document.createElement('div')
+  document.body.append(host)
+  const root = createRoot(host)
+  try {
+    await act(async () => root.render(<FileExplorer rootPath="/read-failure" />))
+    await act(async () => { await vi.runAllTimersAsync() })
+    expect(host.querySelector('[role="alert"]')?.textContent).toContain('Could not load files')
+    expect(host.textContent).not.toContain('No files found')
+    mocks.read.mockResolvedValue([{ path: '/read-failure/file.ts', name: 'file.ts', isDirectory: false, fileExtension: 'ts' }])
+    await act(async () => [...host.querySelectorAll('button')].find(button => button.textContent === 'Retry')!.click())
+    await act(async () => { await vi.advanceTimersByTimeAsync(150) })
+    expect(host.querySelector('[role="alert"]')).toBeNull()
+    expect(host.querySelector('[data-filepath="/read-failure/file.ts"]')).not.toBeNull()
+  } finally { await act(async () => root.unmount()); host.remove() }
+})
diff --git a/src/renderer/sidebar/FileExplorer.tsx b/src/renderer/sidebar/FileExplorer.tsx
index 864e26b6..0ff3c02e 100644
--- a/src/renderer/sidebar/FileExplorer.tsx
+++ b/src/renderer/sidebar/FileExplorer.tsx
@@ -6,6 +6,7 @@ import { placementForPanel } from '../lib/workspace/canvasAccess'
 
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import log from '../lib/logger'
+import { errorMessage } from '../lib/errorMessage'
 import { RotateCw as ArrowClockwise, FilePlus, FolderPlus, Search as MagnifyingGlass, X } from 'lucide-react'
 import type { FileTreeNode as FileTreeNodeType } from '../../shared/types'
 import { VirtualFileRows, type VirtualFileRowsHandle } from './VirtualFileRows'
@@ -70,6 +71,7 @@ const recentExplorerViews = new Map<string, ExplorerView>()
 export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceId, panelId, scopeControl, onOpenFiles, compact = false }) => {
   const [nodes, setNodes] = useState<FileTreeNodeType[]>([])
   const [isLoading, setIsLoading] = useState(false)
+  const [loadError, setLoadError] = useState<string | null>(null)
   // Expansion state is owned by the explorer (not each FileTreeNode) so this
   // component knows the tree's full visible structure — needed for keyboard
   // navigation (issue #268) and as the ordering source for shift-click ranges.
@@ -257,6 +259,7 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceI
   const viewRef = useRef<ExplorerView>({ nodes, children: childrenCache, expanded: expandedPaths, selected: selectedPaths })
   useEffect(() => {
     rootPathRef.current = rootPath
+    setLoadError(null)
     const cacheKey = `${selectedWorkspaceId}:${rootPath}`
     const cached = recentExplorerViews.get(cacheKey)
     childRequests.current.clear()
@@ -284,8 +287,16 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceI
           }
         }
       },
-      apply: (path, entries) => {
-        if (path === rootPath) { setNodes(entries ?? []); setIsLoading(false) }
+      apply: (path, entries, error) => {
+        if (path === rootPath) {
+          setIsLoading(false)
+          if (error !== undefined) {
+            setLoadError(errorMessage(error, 'Could not load files.'))
+            return
+          }
+          setLoadError(null)
+          setNodes(entries ?? [])
+        }
         else setChildrenCache((previous) => {
           const next = new Map(previous)
           if (entries) next.set(path, entries)
@@ -690,10 +701,25 @@ export const FileExplorer: React.FC<FileExplorerProps> = ({ rootPath, workspaceI
         </div>
       )}
 
+      {loadError && (
+        <div role="alert" className="shrink-0 px-3 py-3 text-xs text-muted">
+          <p className="font-medium text-primary">Could not load files</p>
+          <p className="mt-1 break-words">{loadError}</p>
+          <button type="button" className="mt-2 rounded-md bg-surface-2 px-3 py-1.5 text-primary hover:bg-hover" onClick={async () => {
+            if (isLocalLocator(rootPath)) {
+              try {
+                const result = await window.electronAPI.runtimeRetryLocal()
+                if (!result.ok) { setLoadError(result.error ?? 'Could not reconnect to local files.'); return }
+              } catch (error) { setLoadError(errorMessage(error)); return }
+            }
+            loadTree(rootPath)
+          }}>Retry</button>
+        </div>
+      )}
       {/* Tree content */}
       {isLoading && nodes.length === 0 ? (
         <LoadingState label="Loading files…" size={14} className="flex-1 text-xs" />
-      ) : nodes.length === 0 && !rootCreating ? (
+      ) : nodes.length === 0 && loadError && !rootCreating ? null : nodes.length === 0 && !rootCreating ? (
         <div
           className="flex flex-col items-center justify-center flex-1 text-muted text-xs gap-2 p-4"
           onContextMenu={handleRootContextMenu}
diff --git a/src/renderer/sidebar/explorerRefresh.ts b/src/renderer/sidebar/explorerRefresh.ts
index d1a04b69..59c5c7ff 100644
--- a/src/renderer/sidebar/explorerRefresh.ts
+++ b/src/renderer/sidebar/explorerRefresh.ts
@@ -6,7 +6,7 @@ export function createExplorerRefresh<T>(options: {
   root: string
   loaded: () => Iterable<string>
   read: (path: string) => Promise<T>
-  apply: (path: string, value: T | null) => void
+  apply: (path: string, value: T | null, error?: unknown) => void
   remove: (path: string) => void
 }) {
   const pending = new Set<string>()
@@ -29,11 +29,15 @@ export function createExplorerRefresh<T>(options: {
         await Promise.all(paths.map(async (path) => {
           inFlight.add(path)
           let value: T | null = null
-          try { value = await options.read(path) } catch { /* deleted/unreadable */ }
+          let readError: unknown
+          try { value = await options.read(path) } catch (error) { readError = error }
           inFlight.delete(path)
           const removed = removedInFlight.delete(path)
           if (!disposed && !pending.has(path)) {
-            if (!removed) options.apply(path, value)
+            if (!removed) {
+              if (readError !== undefined) options.apply(path, value, readError)
+              else options.apply(path, value)
+            }
             for (const resolve of waiters.get(path) ?? []) resolve()
             waiters.delete(path)
           }
diff --git a/src/renderer/stores/appStore/panelSlice.ts b/src/renderer/stores/appStore/panelSlice.ts
index a4bb210c..a2aa4ca8 100644
--- a/src/renderer/stores/appStore/panelSlice.ts
+++ b/src/renderer/stores/appStore/panelSlice.ts
@@ -41,7 +41,6 @@ type PanelSliceActions = Pick<
   | 'createReview'
   | 'createCanvas'
   | 'createAgent'
-  | 'createDocument'
   | 'closePanel'
   | 'updatePanelTitle'
   | 'updatePanelTitleFromAgent'
@@ -155,23 +154,6 @@ export function createPanelSlice(set: AppSet, get: AppGet): PanelSliceActions {
       return addAndPlacePanel(set, get, workspaceId, panel, withDefaultSize('editor', placement), position)
     },
 
-    createDocument(workspaceId, filePath?, documentType?, position?, placement?) {
-      const panelId = generateId()
-      const worktreeId = worktreeIdForPath(workspaceId, filePath)
-      if (filePath) recordRecentFile(workspaceId, filePath)
-      const fileName = (filePath && pathDisplayName(filePath)) || 'Document'
-      const panel: PanelState = {
-        id: panelId,
-        type: 'document',
-        title: fileName,
-        isDirty: false,
-        filePath,
-        documentType,
-        ...(worktreeId ? { worktreeId } : {}),
-      }
-      return addAndPlacePanel(set, get, workspaceId, panel, withDefaultSize('document', placement), position)
-    },
-
     createReview(workspaceId, repoPath, initial?, position?, placement?) {
       const panelId = generateId()
       const worktreeId = worktreeIdForPath(workspaceId, repoPath)
diff --git a/src/renderer/stores/appStore/types.ts b/src/renderer/stores/appStore/types.ts
index a7cc9956..2e63e04b 100644
--- a/src/renderer/stores/appStore/types.ts
+++ b/src/renderer/stores/appStore/types.ts
@@ -103,7 +103,6 @@ export interface AppStoreActions {
     worktreeId?: string,
     threadId?: string,
   ) => string
-  createDocument: (workspaceId: string, filePath?: string, documentType?: 'pdf' | 'docx' | 'image', position?: Point, placement?: PanelPlacement) => string
 
   // Remove stale dock references without creating panels in an empty workspace.
   reconcileWorkspaceDock: (workspaceId: string) => void
diff --git a/src/renderer/stores/canvasStore.ts b/src/renderer/stores/canvasStore.ts
index 93d45bd1..69b234c4 100644
--- a/src/renderer/stores/canvasStore.ts
+++ b/src/renderer/stores/canvasStore.ts
@@ -338,7 +338,7 @@ export function selectVisibleNodeIds(
 
   const result: string[] = []
   for (const n of sorted) {
-    if (n.id === focusedNodeId || n.isPinned || keepAlive.has(n.id)) {
+    if (n.preMaximizeOrigin != null || n.id === focusedNodeId || n.isPinned || keepAlive.has(n.id)) {
       result.push(n.id)
       continue
     }
diff --git a/src/renderer/stores/canvasVisibleNodes.test.tsx b/src/renderer/stores/canvasVisibleNodes.test.tsx
index f1d6d8d1..9cac2a03 100644
--- a/src/renderer/stores/canvasVisibleNodes.test.tsx
+++ b/src/renderer/stores/canvasVisibleNodes.test.tsx
@@ -53,4 +53,23 @@ describe('useVisibleNodeIds zoom settling', () => {
     act(() => { second = store.getState().addNode('second', 'editor', { x: 200, y: 100 }, { width: 100, height: 100 }) })
     expect(host.firstElementChild?.getAttribute('data-ids')).toBe(`${first},${second}`)
   })
+
+  it('keeps a maximized node mounted after losing focus in a collapsed canvas', () => {
+    const store = createCanvasStore()
+    store.getState().setContainerSize({ width: 800, height: 600 })
+    const id = store.getState().addNode('terminal', 'terminal', { x: 200, y: 200 }, { width: 640, height: 400 })
+    const Probe = () => <div data-ids={useVisibleNodeIds(store, new Set()).join(',')} />
+    act(() => root.render(<Probe />))
+    act(() => {
+      store.getState().toggleMaximize(id, { width: 800, height: 600 })
+      store.getState().setContainerSize({ width: 800, height: 1 })
+      store.getState().unfocus()
+    })
+    expect(host.firstElementChild?.getAttribute('data-ids')).toBe(id)
+    act(() => {
+      store.getState().toggleMaximize(id, { width: 800, height: 600 })
+      store.getState().unfocus()
+    })
+    expect(host.firstElementChild?.getAttribute('data-ids')).toBe('')
+  })
 })
diff --git a/src/renderer/stores/detachedDockPlacement.test.ts b/src/renderer/stores/detachedDockPlacement.test.ts
index 92e008c5..72ec06ec 100644
--- a/src/renderer/stores/detachedDockPlacement.test.ts
+++ b/src/renderer/stores/detachedDockPlacement.test.ts
@@ -58,7 +58,7 @@ describe.each(['main', 'detached'])('%s empty dock panel placement', (owner) =>
     useWindowPanelStore.setState({ panels: [] })
   })
 
-  it.each(['terminal', 'agent', 'editor', 'browser', 'review', 'document', 'surface'] as const)('places %s directly for implicit, keyboard, and host API sources', (type) => {
+  it.each(['terminal', 'agent', 'editor', 'browser', 'review', 'surface'] as const)('places %s directly for implicit, keyboard, and host API sources', (type) => {
     const foreign = getOrCreateCanvasStoreForPanel('foreign-canvas')
     setActivePanel('foreign-canvas')
     const placements = [undefined, placementForActivePanel(), placementForBackgroundPanel(wsId), { target: 'canvas' as const, canvasPanelId: 'closed-canvas' }]
diff --git a/src/renderer/styles/globals.css b/src/renderer/styles/globals.css
index e554399d..0fcc9c40 100644
--- a/src/renderer/styles/globals.css
+++ b/src/renderer/styles/globals.css
@@ -548,3 +548,22 @@
   .review-worktree { max-width: 70px; }
   .review-run-status { width: 6px; height: 6px; overflow: hidden; font-size: 0; border-radius: 50%; background: currentColor; }
 }
+
+@keyframes screenshot-slide-from-right {
+  from { opacity: 0; transform: translateX(28px); }
+  to { opacity: 1; transform: translateX(0); }
+}
+
+@keyframes screenshot-slide-from-left {
+  from { opacity: 0; transform: translateX(-28px); }
+  to { opacity: 1; transform: translateX(0); }
+}
+
+.screenshot-viewer-image-in {
+  animation-duration: 180ms;
+  animation-timing-function: ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .screenshot-viewer-image-in { animation: none !important; }
+}
diff --git a/src/renderer/ui/CommandPalette.tsx b/src/renderer/ui/CommandPalette.tsx
index dbac5fec..15553579 100644
--- a/src/renderer/ui/CommandPalette.tsx
+++ b/src/renderer/ui/CommandPalette.tsx
@@ -363,7 +363,7 @@ export const CommandPalette: React.FC = () => {
       const wsId = appStore.selectedWorkspaceId
       const ws = appStore.workspaces.find((w) => w.id === wsId)
       const existing = Object.values(ws?.panels ?? {}).find(
-        (panel) => (panel.type === 'editor' || panel.type === 'document') && panel.filePath === file.path,
+        (panel) => (panel.type === 'editor') && panel.filePath === file.path,
       )
       const panelId = existing?.id ?? openFileAsPanel(wsId, file.path, undefined, placementForActivePanel())
       void revealPanel(wsId, panelId, { retry: true })
diff --git a/src/renderer/ui/Popover.tsx b/src/renderer/ui/Popover.tsx
index b51e6b4c..ac0366c8 100644
--- a/src/renderer/ui/Popover.tsx
+++ b/src/renderer/ui/Popover.tsx
@@ -45,7 +45,7 @@ export function useDismissableLayer({
 }
 
 export const POPOVER_SURFACE =
-  'rounded-lg border border-strong bg-surface-4/98 backdrop-blur-xl shadow-[0_12px_32px_var(--shadow-node)]'
+  'rounded-2xl border border-subtle bg-surface-3 shadow-lg'
 
 export type ViewportPopoverPosition = {
   top: number
diff --git a/src/renderer/ui/SharedPrimitives.test.tsx b/src/renderer/ui/SharedPrimitives.test.tsx
index d887ec2e..7ec726ae 100644
--- a/src/renderer/ui/SharedPrimitives.test.tsx
+++ b/src/renderer/ui/SharedPrimitives.test.tsx
@@ -3,7 +3,7 @@ import { createRoot, type Root } from 'react-dom/client'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Button } from './Button'
 import { Modal } from './Modal'
-import { useDismissableLayer } from './Popover'
+import { POPOVER_SURFACE, useDismissableLayer } from './Popover'
 import { Tooltip } from './Tooltip'
 
 ;(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true
@@ -29,6 +29,13 @@ function render(node: ReactNode): void {
 }
 
 describe('shared UI primitives', () => {
+  it('keeps popup surfaces aligned with the Cate menu treatment', () => {
+    expect(POPOVER_SURFACE).toContain('rounded-2xl')
+    expect(POPOVER_SURFACE).toContain('border-subtle')
+    expect(POPOVER_SURFACE).toContain('bg-surface-3')
+    expect(POPOVER_SURFACE).toContain('shadow-lg')
+  })
+
   it('shows an associated tooltip from keyboard focus and dismisses it with Escape', () => {
     vi.useFakeTimers()
     render(<Tooltip label="Refresh"><button type="button">Refresh</button></Tooltip>)
diff --git a/src/shared/cliPermissions.ts b/src/shared/cliPermissions.ts
index 5c0a73bf..55cf3d8c 100644
--- a/src/shared/cliPermissions.ts
+++ b/src/shared/cliPermissions.ts
@@ -120,7 +120,7 @@ export const CLI_PERMISSIONS: CliPermissionSurface[] = [
       access: 'Control',
       code: 'editor-control-disabled',
       detail:
-        '`cate editor open <path[:line]>` — open a file in an editor panel (a PDF or docx opens a document panel).',
+        '`cate editor open <path[:line]>` — open a file in Files, including image, PDF, and DOCX previews.',
     },
   },
   {
diff --git a/src/shared/electron-api.d.ts b/src/shared/electron-api.d.ts
index 9c8f0bb1..113e7f95 100644
--- a/src/shared/electron-api.d.ts
+++ b/src/shared/electron-api.d.ts
@@ -720,6 +720,7 @@ export interface ElectronAPI {
   getRecentScreenshot(): Promise<RecentScreenshot[]>
   onRecentScreenshotChanged(callback: (screenshot: RecentScreenshot[]) => void): () => void
   dragRecentScreenshot(id: string): Promise<void>
+  saveRecentScreenshot(id: string, dataUrl: string): Promise<RecentScreenshot>
   /** Initiate a native OS file drag from the renderer. */
   nativeFileDrag(filePath: string): Promise<void>
 
diff --git a/src/shared/ipc-channels.ts b/src/shared/ipc-channels.ts
index 19e9c351..6cbf686f 100644
--- a/src/shared/ipc-channels.ts
+++ b/src/shared/ipc-channels.ts
@@ -445,3 +445,5 @@ export const REMOTE_CONNECTIONS_LIST = 'remote-connections:list'
 export const REMOTE_CONNECTIONS_SAVE = 'remote-connections:save'
 export const REMOTE_CONNECTIONS_REMOVE = 'remote-connections:remove'
 export const REMOTE_CONNECTIONS_CHANGED = 'remote-connections:changed'
+
+export const RECENT_SCREENSHOT_SAVE = 'recentScreenshot:save'
diff --git a/src/shared/panels.test.ts b/src/shared/panels.test.ts
index d1159f42..a7063f2d 100644
--- a/src/shared/panels.test.ts
+++ b/src/shared/panels.test.ts
@@ -1,3 +1,4 @@
+import { migrateNavigationPanel } from './panels'
 import { describe, it, expect } from 'vitest'
 import {
   SPLIT_MENU_PANEL_TYPES,
@@ -56,7 +57,7 @@ describe('panel capabilities', () => {
 
   it('owns command-palette navigation policy', () => {
     expect(isNavigablePanelType('terminal')).toBe(true)
-    expect(isNavigablePanelType('document')).toBe(true)
+    expect(isNavigablePanelType('document')).toBe(false)
     expect(isNavigablePanelType('canvas')).toBe(false)
     expect(isNavigablePanelType('unknown')).toBe(false)
   })
@@ -65,3 +66,9 @@ describe('panel capabilities', () => {
     expect(SPLIT_MENU_PANEL_TYPES).toEqual(['editor', 'terminal', 'browser', 'canvas', 'agent', 'review'])
   })
 })
+
+ it('migrates document tabs into Files without losing their identity or path', () => {
+  expect(migrateNavigationPanel({ id: 'preview', type: 'document', filePath: '/repo/image.png' })).toEqual({
+    id: 'preview', type: 'editor', filePath: '/repo/image.png', sidebarView: 'explorer',
+  })
+})
diff --git a/src/shared/panels.ts b/src/shared/panels.ts
index b6ea2136..c60b8d43 100644
--- a/src/shared/panels.ts
+++ b/src/shared/panels.ts
@@ -152,21 +152,6 @@ export const PANEL_DEFINITIONS = {
     keepMountedOffscreen: true,
     keepMountedWhenTabHidden: true,
   },
-  document: {
-    type: 'document',
-    label: 'Document',
-    brandColor: '#AF52DE',
-    mutedColor: '#7a4a9a',
-    tintClass: 'text-purple-400',
-    defaultSize: { width: 700, height: 500 },
-    minimumSize: { width: 300, height: 250 },
-    ghostSvg: ghost('rgb(175,82,222)', '<path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><circle cx="12" cy="15" r="3"/>'),
-    canLiveOnCanvas: true,
-    worktreeBinding: false,
-    navigable: true,
-    keepMountedOffscreen: false,
-    keepMountedWhenTabHidden: false,
-  },
   review: {
     type: 'review',
     splitMenuOrder: 8,
@@ -263,6 +248,7 @@ export function resolvePanelSize(type: PanelType, _settings?: unknown): Size {
 /** Normalize retired navigation surfaces at persistence/transfer boundaries.
  * Preserve IDs and placement; Files and Search now share the editor surface. */
 export function migrateNavigationPanel<T extends { type: string; sidebarView?: 'explorer' | 'search' | 'git' }>(panel: T): T {
+  if (panel.type === 'document') return { ...panel, type: 'editor', sidebarView: 'explorer' }
   if (panel.type !== 'navigation' && panel.type !== 'search') return panel
   return { ...panel, type: 'editor', sidebarView: panel.type === 'search' ? 'search' : panel.sidebarView ?? 'explorer' }
 }
diff --git a/src/shared/recentScreenshot.ts b/src/shared/recentScreenshot.ts
index b728871e..0950aac6 100644
--- a/src/shared/recentScreenshot.ts
+++ b/src/shared/recentScreenshot.ts
@@ -1,5 +1,7 @@
 export interface RecentScreenshot {
   id: string
   filePath: string
+  annotated?: boolean
+  /** Small thumbnail for the stack and native drag icon. Read filePath for the original image. */
   dataUrl: string
 }
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 3feb982d..8c2b6d1c 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -32,7 +32,7 @@ export interface Rect {
 // Panel types
 // -----------------------------------------------------------------------------
 
-export type PanelType = 'terminal' | 'browser' | 'editor' | 'canvas' | 'agent' | 'document' | 'review' | 'surface'
+export type PanelType = 'terminal' | 'browser' | 'editor' | 'canvas' | 'agent' | 'review' | 'surface'
 
 // -----------------------------------------------------------------------------
 // Canvas node
@@ -248,8 +248,6 @@ export interface PanelState {
    *  the terminal uses the workspace's `rootPath`. Set when the terminal was
    *  created from a dropped folder or worktree to scope it to that path. */
   cwd?: string
-  /** Document panels only: sub-type discriminator for the viewer. */
-  documentType?: 'pdf' | 'docx' | 'image'
   /** Checkout affinity for terminals, Agent, file-backed, and review panels. */
   worktreeId?: string
   /** Terminal panels only. Set to true the first time the user renames the
@@ -1248,8 +1246,6 @@ export interface ProjectPanelRef {
   activeTabId?: string
   /** Browser panels only: per-panel proxy URL (see PanelState.proxyUrl). */
   proxyUrl?: string
-  /** Document panels only: sub-type discriminator for the viewer. */
-  documentType?: 'pdf' | 'docx' | 'image'
 }
 
 // -----------------------------------------------------------------------------
@@ -1500,7 +1496,7 @@ export interface AppSettings {
   cliPanelControlEnabled: boolean
   /** Read the active editor panel's file. On by default. */
   cliEditorReadEnabled: boolean
-  /** `cate editor open` — open a file in an editor/document panel. On by default. */
+  /** `cate editor open` — open a file in Files. On by default. */
   cliEditorControlEnabled: boolean
   /** `cate notify` — post a desktop notification. On by default. */
   cliNotifyEnabled: boolean
@@ -1688,7 +1684,6 @@ export const PANEL_CANVAS_DROP_SIZES: Record<PanelType, Size> = {
   editor: { width: 540, height: 420 },
   canvas: { width: 640, height: 480 },
   agent: { width: 520, height: 440 },
-  document: { width: 640, height: 480 },
   review: { width: 820, height: 560 },
 }
 

From dfd63992667c08c0ed7e7001814c917e8302f464 Mon Sep 17 00:00:00 2001
From: Anton <antonhorn@icloud.com>
Date: Fri, 11 Sep 2026 00:28:50 +0200
Subject: [PATCH 5/7] Refine canvas drag, screenshots, and dock presentation

---
 e2e/detached-panels.spec.ts                   |  79 ++++++
 src/main/ipc/recentScreenshot.test.ts         |  23 +-
 src/main/ipc/recentScreenshot.ts              |  19 +-
 src/preload/index.ts                          |   2 +
 .../canvas/Canvas.topOverlay.test.tsx         |  36 ---
 src/renderer/canvas/Canvas.tsx                |  18 +-
 .../canvas/CanvasNode.dragPreview.test.tsx    | 148 ++++++++++
 .../canvas/CanvasNode.groupDrag.test.tsx      | 139 +++++++---
 src/renderer/canvas/CanvasNode.tsx            | 209 ++++++++------
 src/renderer/canvas/CanvasToolbar.test.ts     |   6 +-
 src/renderer/canvas/CanvasToolbar.tsx         |   7 +-
 .../canvas/RecentScreenshotButton.test.tsx    |  21 +-
 .../canvas/RecentScreenshotButton.tsx         |  48 ++--
 .../canvas/ScreenshotDrawing.test.tsx         |  61 +++++
 src/renderer/canvas/ScreenshotDrawing.tsx     | 215 ++++++++++++++-
 src/renderer/canvas/useCanvasNodeStyle.ts     |  19 +-
 src/renderer/docking/DockLayoutRenderer.tsx   |   6 +-
 src/renderer/docking/DockSplitContainer.tsx   |  12 +-
 .../docking/DockSplitMaximize.test.tsx        |  47 ----
 src/renderer/docking/DockTabStack.tsx         |  46 +++-
 src/renderer/docking/SurfacePanels.test.tsx   |  44 ++-
 src/renderer/drag/__tests__/harness.tsx       |   5 -
 .../drag/__tests__/scenarios.test.tsx         |  55 +---
 src/renderer/drag/useDragOp.ts                |  30 +-
 src/renderer/panels/CanvasPanel.tsx           |   4 +
 src/renderer/panels/TerminalPanel.tsx         |   6 +-
 src/renderer/shells/DockWindowShell.tsx       |   2 +-
 src/renderer/shells/MainWindowShell.tsx       |  24 +-
 src/renderer/stores/DockStoreContext.tsx      |   6 +
 src/renderer/stores/canvas/nodesSlice.ts      |  41 +--
 .../stores/canvas/sanitizeNodes.test.ts       |   9 -
 src/renderer/stores/canvas/sanitizeNodes.ts   |  20 +-
 .../stores/canvas/selectionModel.test.ts      |  13 +-
 src/renderer/stores/canvas/storeTypes.ts      |   1 -
 .../stores/canvasStore.lifecycle.test.ts      |  37 ---
 src/renderer/stores/canvasStore.test.ts       |   9 -
 src/renderer/stores/canvasStore.ts            |   2 +-
 .../stores/canvasVisibleNodes.test.tsx        |  18 --
 .../stores/dockStore.maximize.test.ts         |  48 ----
 .../stores/dockStore.presentation.test.ts     | 258 ++++++++++++++++++
 src/renderer/stores/dockStore.ts              | 156 +++++++++--
 src/shared/electron-api.d.ts                  |   1 +
 src/shared/ipc-channels.ts                    |   1 +
 src/shared/types.ts                           |   7 -
 44 files changed, 1300 insertions(+), 658 deletions(-)
 create mode 100644 src/renderer/canvas/CanvasNode.dragPreview.test.tsx
 create mode 100644 src/renderer/canvas/ScreenshotDrawing.test.tsx
 delete mode 100644 src/renderer/docking/DockSplitMaximize.test.tsx
 delete mode 100644 src/renderer/stores/dockStore.maximize.test.ts
 create mode 100644 src/renderer/stores/dockStore.presentation.test.ts

diff --git a/e2e/detached-panels.spec.ts b/e2e/detached-panels.spec.ts
index c4a588d2..ded79c31 100644
--- a/e2e/detached-panels.spec.ts
+++ b/e2e/detached-panels.spec.ts
@@ -60,6 +60,85 @@ test('Files root terminal action places the terminal in the visible detached doc
   await expect(detached.locator(`[data-tab-panel-id="${terminal}"]`)).toBeVisible()
 })
 
+test('screenshot preview and comment editing stay in the detached canvas window', async () => {
+  await app.evaluate(({ ipcMain }) => {
+    const svg = `data:image/svg+xml;base64,${Buffer.from('<svg xmlns="http://www.w3.org/2000/svg" width="800" height="600"><rect width="800" height="600" fill="#345"/></svg>').toString('base64')}`
+    const shots = [
+      { id: 'detached-shot', filePath: '/tmp/detached-shot.png', dataUrl: svg },
+      { id: 'detached-shot-2', filePath: '/tmp/detached-shot-2.png', dataUrl: svg },
+    ]
+    ipcMain.removeHandler('recentScreenshot:get')
+    ipcMain.removeHandler('recentScreenshot:read')
+    ipcMain.removeHandler('recentScreenshot:save')
+    ipcMain.handle('recentScreenshot:get', () => shots)
+    ipcMain.handle('recentScreenshot:read', () => svg)
+    ipcMain.handle('recentScreenshot:save', (_event, _id, dataUrl) => {
+      ;(globalThis as typeof globalThis & { __detachedAnnotation?: string }).__detachedAnnotation = dataUrl
+      return { ...shots[0], id: 'detached-saved', filePath: '/tmp/detached-saved.png', dataUrl, annotated: true }
+    })
+  })
+  const id = await main.evaluate(() => window.__cateE2E!.createPanel('canvas'))
+  const detached = await detach(id)
+  const previewButton = detached.getByRole('button', { name: 'Open screenshot preview' }).first()
+  await expect(previewButton).toBeVisible()
+  await previewButton.click()
+  const viewer = detached.getByRole('dialog', { name: 'Screenshot preview' })
+  await expect(viewer).toBeVisible()
+  await expect(main.getByRole('dialog', { name: 'Screenshot preview' })).toHaveCount(0)
+  await expect(detached.getByRole('link', { name: 'Download screenshot' })).toHaveAttribute('download', 'detached-shot.png')
+  await viewer.getByRole('button', { name: 'Next screenshot' }).click()
+  await expect(detached.getByText('2 / 2')).toBeVisible()
+  await expect(viewer.getByRole('img', { name: 'Screenshot 2 of 2' })).toBeVisible()
+  await viewer.getByRole('button', { name: 'Zoom in' }).click()
+  await expect(viewer.getByRole('button', { name: 'Fit screenshot' })).not.toHaveText('100%')
+  await expect(viewer.getByRole('toolbar', { name: 'Screenshot drawing tools' })).toBeVisible()
+  const annotation = detached.getByLabel('Annotate screenshot')
+  const box = await annotation.boundingBox()
+  if (!box) throw new Error('Missing detached screenshot annotation bounds')
+  await detached.mouse.move(box.x + box.width * 0.2, box.y + box.height * 0.2)
+  await detached.mouse.down()
+  await detached.mouse.move(box.x + box.width * 0.3, box.y + box.height * 0.3)
+  await detached.mouse.up()
+  await detached.getByRole('button', { name: 'Add comment' }).click()
+  await annotation.locator('rect').click({ position: { x: box.width / 2, y: box.height / 2 } })
+  await detached.getByRole('textbox', { name: 'Comment 1' }).fill('Detached canvas comment')
+  const comment = detached.locator('foreignObject').last()
+  const initialX = Number(await comment.getAttribute('x'))
+  const handle = detached.getByRole('button', { name: 'Move comment 1' })
+  const handleBox = await handle.boundingBox()
+  if (!handleBox) throw new Error('Missing detached comment drag handle')
+  await detached.mouse.move(handleBox.x + handleBox.width / 2, handleBox.y + handleBox.height / 2)
+  await detached.mouse.down()
+  await detached.mouse.move(handleBox.x + handleBox.width / 2 + 50, handleBox.y + handleBox.height / 2 + 20)
+  await detached.mouse.up()
+  await expect.poll(async () => Number(await comment.getAttribute('x'))).toBeGreaterThan(initialX)
+  const initialWidth = Number(await comment.getAttribute('width'))
+  const initialHeight = Number(await comment.getAttribute('height'))
+  const scaleHandle = detached.locator('[aria-label="Resize comment 1"]')
+  const scaleBox = await scaleHandle.boundingBox()
+  if (!scaleBox) throw new Error('Missing detached comment scale handle')
+  await detached.mouse.move(scaleBox.x + scaleBox.width - 2, scaleBox.y + scaleBox.height / 2)
+  await detached.mouse.down()
+  await detached.mouse.move(scaleBox.x + scaleBox.width + 38, scaleBox.y + scaleBox.height / 2)
+  await detached.mouse.up()
+  await expect.poll(async () => Number(await comment.getAttribute('width'))).toBeGreaterThan(initialWidth)
+  await expect.poll(async () => Number(await comment.getAttribute('height'))).toBe(initialHeight)
+  const calloutGroup = comment.locator('..')
+  const initialTransform = await calloutGroup.getAttribute('transform')
+  const rotateHandle = detached.locator('[aria-label="Rotate comment 1"]')
+  await expect(rotateHandle).toHaveCSS('cursor', /url/)
+  const rotateBox = await rotateHandle.boundingBox()
+  if (!rotateBox) throw new Error('Missing detached comment rotation handle')
+  await detached.mouse.move(rotateBox.x + rotateBox.width / 2, rotateBox.y + 2)
+  await detached.mouse.down()
+  await detached.mouse.move(rotateBox.x + rotateBox.width / 2 + 45, rotateBox.y + 27)
+  await detached.mouse.up()
+  await expect.poll(() => calloutGroup.getAttribute('transform')).not.toBe(initialTransform)
+  await detached.getByRole('button', { name: 'Save' }).click()
+  await expect(detached.getByRole('dialog', { name: 'Screenshot preview' })).toHaveCount(0)
+  await expect.poll(() => app.evaluate(() => (globalThis as typeof globalThis & { __detachedAnnotation?: string }).__detachedAnnotation?.startsWith('data:image/png;base64,'))).toBe(true)
+})
+
 async function chooseNativeMenu(choice: string) {
   await app.evaluate(({ ipcMain }, choice) => {
     ipcMain.removeHandler('menu:showContext')
diff --git a/src/main/ipc/recentScreenshot.test.ts b/src/main/ipc/recentScreenshot.test.ts
index 96836fb6..67ea7465 100644
--- a/src/main/ipc/recentScreenshot.test.ts
+++ b/src/main/ipc/recentScreenshot.test.ts
@@ -1,24 +1,24 @@
 import path from 'node:path'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { RECENT_SCREENSHOT_GET, RECENT_SCREENSHOT_DRAG, RECENT_SCREENSHOT_CHANGED, RECENT_SCREENSHOT_SAVE } from '../../shared/ipc-channels'
+import { RECENT_SCREENSHOT_GET, RECENT_SCREENSHOT_DRAG, RECENT_SCREENSHOT_CHANGED, RECENT_SCREENSHOT_READ, RECENT_SCREENSHOT_SAVE } from '../../shared/ipc-channels'
 import { registerRecentScreenshotHandlers } from './recentScreenshot'
 
 const mocks = vi.hoisted(() => ({
   handle: vi.fn(), on: vi.fn(), watch: vi.fn(), close: vi.fn(), watcherOn: vi.fn(),
   run: vi.fn(), stat: vi.fn(), thumbnail: vi.fn(), broadcast: vi.fn(), grant: vi.fn(), drag: vi.fn(),
-  runtimeGrant: vi.fn(), mkdir: vi.fn(), writeFile: vi.fn(), decode: vi.fn(),
+  runtimeGrant: vi.fn(), writeFile: vi.fn(), decode: vi.fn(), fromPath: vi.fn(),
 }))
 vi.mock('node:child_process', () => ({ execFile: (...args: unknown[]) => mocks.run(...args) }))
 vi.mock('node:util', () => ({ promisify: () => (...args: unknown[]) => new Promise((resolve, reject) => {
   mocks.run(...args, (error: Error | null, stdout: string, stderr: string) => error ? reject(error) : resolve({ stdout, stderr }))
 }) }))
-vi.mock('node:fs/promises', () => ({ stat: mocks.stat, writeFile: mocks.writeFile, mkdir: mocks.mkdir }))
+vi.mock('node:fs/promises', () => ({ stat: mocks.stat, writeFile: mocks.writeFile }))
 vi.mock('chokidar', () => ({ watch: mocks.watch }))
 vi.mock('electron', () => ({
   app: { getPath: (key: string) => key === 'desktop' ? '/desktop' : '/home', on: mocks.on },
   ipcMain: { handle: mocks.handle },
   BrowserWindow: { getAllWindows: () => [{ id: 1 }, { id: 2 }] },
-  nativeImage: { createThumbnailFromPath: mocks.thumbnail, createFromDataURL: mocks.decode },
+  nativeImage: { createThumbnailFromPath: mocks.thumbnail, createFromDataURL: mocks.decode, createFromPath: mocks.fromPath },
 }))
 vi.mock('../windowRegistry', () => ({ broadcastToAll: mocks.broadcast, windowFromEvent: () => ({ id: 1 }) }))
 vi.mock('./pathValidation', () => ({ grantFileAccess: mocks.grant }))
@@ -39,6 +39,7 @@ beforeEach(async () => {
   vi.spyOn(process, 'platform', 'get').mockReturnValue('darwin')
   mocks.grant.mockImplementation(async (_windowId, filePath) => filePath)
   mocks.decode.mockReturnValue('icon')
+  mocks.fromPath.mockReturnValue({ isEmpty: () => false, toDataURL: () => 'data:image/png;base64,converted' })
   mocks.runtimeGrant.mockResolvedValue(undefined)
   mocks.run.mockImplementation((_command, _args, _options, callback) => callback(null, '', ''))
   mocks.watch.mockReturnValue({ on: mocks.watcherOn, close: mocks.close })
@@ -139,7 +140,7 @@ describe('recent macOS screenshot', () => {
     mocks.decode.mockReturnValue({ isEmpty: () => false, toPNG: () => png })
     const saved = await invoke(RECENT_SCREENSHOT_SAVE, shot.id, 'data:image/png;base64,test')
     expect(saved.annotated).toBe(true)
-    expect(saved.filePath).toMatch(/^\/home\/screenshots\/shot-annotated-.*\.png$/)
+    expect(saved.filePath).toMatch(/^\/desktop\/shot-annotated-.*\.png$/)
     expect(mocks.writeFile).toHaveBeenCalledWith(saved.filePath, png, { flag: 'wx' })
     expect(mocks.runtimeGrant).toHaveBeenCalledWith(saved.filePath, 1)
     expect(mocks.runtimeGrant).toHaveBeenCalledWith(saved.filePath, 2)
@@ -147,9 +148,15 @@ describe('recent macOS screenshot', () => {
     expect(mocks.broadcast).toHaveBeenLastCalledWith(RECENT_SCREENSHOT_CHANGED, [saved, shot])
     await invoke(RECENT_SCREENSHOT_DRAG, saved.id)
     expect(mocks.drag).toHaveBeenCalledWith({ file: saved.filePath, icon: expect.anything() })
-    const evicted = await invoke(RECENT_SCREENSHOT_SAVE, 'evicted-id', 'data:image/png;base64,test')
-    expect(evicted.annotated).toBe(true)
-    expect(evicted.filePath).not.toBe(saved.filePath)
+    await expect(invoke(RECENT_SCREENSHOT_SAVE, 'evicted-id', 'data:image/png;base64,test')).rejects.toThrow('no longer available')
+  })
+
+  it('converts the original through nativeImage before sending it to the renderer', async () => {
+    await emit('add', '/desktop/shot.heic')
+    const [shot] = await invoke(RECENT_SCREENSHOT_GET)
+    await expect(invoke(RECENT_SCREENSHOT_READ, shot.id)).resolves.toBe('data:image/png;base64,converted')
+    expect(mocks.fromPath).toHaveBeenCalledWith('/desktop/shot.heic')
+    await expect(invoke(RECENT_SCREENSHOT_READ, 'missing')).rejects.toThrow('no longer available')
   })
 
   it('switches to a custom screenshot directory and closes watchers on quit', async () => {
diff --git a/src/main/ipc/recentScreenshot.ts b/src/main/ipc/recentScreenshot.ts
index b16301c9..5f79cca4 100644
--- a/src/main/ipc/recentScreenshot.ts
+++ b/src/main/ipc/recentScreenshot.ts
@@ -3,10 +3,10 @@ import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import path from 'node:path'
 import { randomUUID } from 'node:crypto'
-import { stat, writeFile, mkdir } from 'node:fs/promises'
+import { stat, writeFile } from 'node:fs/promises'
 import { watch, type FSWatcher } from 'chokidar'
 import type { RecentScreenshot } from '../../shared/recentScreenshot'
-import { RECENT_SCREENSHOT_GET, RECENT_SCREENSHOT_CHANGED, RECENT_SCREENSHOT_DRAG, RECENT_SCREENSHOT_SAVE } from '../../shared/ipc-channels'
+import { RECENT_SCREENSHOT_GET, RECENT_SCREENSHOT_CHANGED, RECENT_SCREENSHOT_DRAG, RECENT_SCREENSHOT_READ, RECENT_SCREENSHOT_SAVE } from '../../shared/ipc-channels'
 import { broadcastToAll, windowFromEvent } from '../windowRegistry'
 import { grantFileAccess } from './pathValidation'
 import { wrapHandler } from './handlerError'
@@ -48,16 +48,25 @@ export function registerRecentScreenshotHandlers(): void {
     })
   }))
 
+  ipcMain.handle(RECENT_SCREENSHOT_READ, wrapHandler('[recentScreenshot:read]', async (event, id: string) => {
+    if (!windowFromEvent(event)) throw new Error('Screenshot window is no longer available.')
+    const screenshot = current.find(shot => shot.id === id)
+    if (!screenshot) throw new Error('Screenshot is no longer available.')
+    const image = nativeImage.createFromPath(screenshot.filePath)
+    if (image.isEmpty()) throw new Error('Could not read the screenshot.')
+    return image.toDataURL()
+  }))
+
   ipcMain.handle(RECENT_SCREENSHOT_SAVE, wrapHandler('[recentScreenshot:save]', async (event, id: string, dataUrl: string) => {
     const win = windowFromEvent(event)
     const screenshot = current.find(shot => shot.id === id)
     if (!win) throw new Error('Screenshot window is no longer available.')
+    if (!screenshot) throw new Error('Screenshot is no longer available.')
     if (typeof dataUrl !== 'string' || !dataUrl.startsWith('data:image/png;base64,')) throw new Error('Expected a PNG image.')
     const image = nativeImage.createFromDataURL(dataUrl)
     if (image.isEmpty()) throw new Error('Could not read the annotated image.')
-    const directory = path.join(app.getPath('userData'), 'screenshots')
-    await mkdir(directory, { recursive: true })
-    const name = screenshot ? path.basename(screenshot.filePath, path.extname(screenshot.filePath)) : 'screenshot'
+    const directory = path.dirname(screenshot.filePath)
+    const name = path.basename(screenshot.filePath, path.extname(screenshot.filePath))
     const filePath = path.join(directory, `${name}-annotated-${randomUUID()}.png`)
     await writeFile(filePath, image.toPNG(), { flag: 'wx' })
     const thumbnail = await nativeImage.createThumbnailFromPath(filePath, { width: 128, height: 128 })
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 2c6700a8..138978d1 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -225,6 +225,7 @@ import {
   RECENT_SCREENSHOT_CHANGED,
   RECENT_SCREENSHOT_DRAG,
   RECENT_SCREENSHOT_SAVE,
+  RECENT_SCREENSHOT_READ,
   AGENT_HARNESS_GET_PANEL_URL,
   AGENT_HARNESS_GET_USAGE_URL,
   PULL_REQUESTS_LIST,
@@ -486,6 +487,7 @@ const invokeForwarders = {
   nativeFileDrag: makeInvoker<'nativeFileDrag'>(NATIVE_FILE_DRAG),
   getRecentScreenshot: makeInvoker<'getRecentScreenshot'>(RECENT_SCREENSHOT_GET),
   dragRecentScreenshot: makeInvoker<'dragRecentScreenshot'>(RECENT_SCREENSHOT_DRAG),
+  readRecentScreenshot: makeInvoker<'readRecentScreenshot'>(RECENT_SCREENSHOT_READ),
   saveRecentScreenshot: makeInvoker<'saveRecentScreenshot'>(RECENT_SCREENSHOT_SAVE),
   onRecentScreenshotChanged(callback: (screenshot: RecentScreenshot[]) => void): () => void {
     return createIpcListener(RECENT_SCREENSHOT_CHANGED, callback)
diff --git a/src/renderer/canvas/Canvas.topOverlay.test.tsx b/src/renderer/canvas/Canvas.topOverlay.test.tsx
index fe63f62d..cb263c9a 100644
--- a/src/renderer/canvas/Canvas.topOverlay.test.tsx
+++ b/src/renderer/canvas/Canvas.topOverlay.test.tsx
@@ -59,37 +59,6 @@ afterEach(() => {
 })
 
 describe('Canvas top overlay', () => {
-  it('preserves viewport measurements and pan through maximize and restore', () => {
-    const observers: ResizeObserverCallback[] = []
-    vi.stubGlobal('ResizeObserver', class {
-      constructor(callback: ResizeObserverCallback) { observers.push(callback) }
-      observe() {}
-      disconnect() {}
-    })
-    let bounds = new DOMRect(0, 0, 1000, 600)
-    vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(() => bounds)
-    const store = createCanvasStore()
-    act(() => root.render(<CanvasStoreProvider store={store}><Canvas panelId="canvas-one" /></CanvasStoreProvider>))
-    const notify = (width: number, height: number) => act(() => {
-      bounds = new DOMRect(0, 0, width, height)
-      for (const callback of observers) callback([{ contentRect: bounds } as ResizeObserverEntry], {} as ResizeObserver)
-    })
-    notify(1000, 600)
-    act(() => store.getState().setZoomAndOffset(0.5, { x: 20, y: 30 }))
-    let id = ''
-    act(() => {
-      id = store.getState().addNode('terminal', 'terminal', { x: 200, y: 200 }, { width: 640, height: 400 })
-      store.getState().toggleMaximize(id, { width: 1100, height: 700 })
-    })
-    notify(1000, 1)
-    notify(1100, 700)
-    expect(store.getState().containerSize).toEqual({ width: 1000, height: 600 })
-    act(() => store.getState().toggleMaximize(id, { width: 1100, height: 700 }))
-    notify(1000, 600)
-    expect(store.getState().viewportOffset).toEqual({ x: 20, y: 30 })
-    expect(store.getState().zoomLevel).toBe(0.5)
-  })
-
   it('portals above-panel canvas chrome into one transformed screen-space layer', () => {
     const store = createCanvasStore()
     act(() => store.getState().setZoomAndOffset(2, { x: 30, y: 40 }))
@@ -112,11 +81,6 @@ describe('Canvas top overlay', () => {
     expect(overlay.querySelector('[data-toolbar-probe]')).not.toBeNull()
     expect(container.querySelector('[data-canvas-marquee]')).toBeNull()
 
-    const nodeId = store.getState().addNode('editor', 'editor', { x: 100, y: 100 }, { width: 400, height: 300 })
-    act(() => store.getState().toggleMaximize(nodeId, { width: 1280, height: 800 }))
-    expect(overlay.hidden).toBe(true)
-    act(() => store.getState().toggleMaximize(nodeId, { width: 1280, height: 800 }))
-    expect(overlay.hidden).toBe(false)
     expect(world.style.transform).toBe('scale(2) translate(15px, 20px)')
   })
 })
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index fc4f483b..8a2acf7d 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -191,7 +191,6 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
 
   const marquee = useUIStore((s) => s.marquee)
   const showSettings = useUIStore((s) => s.showSettings)
-  const hasMaximizedNode = useCanvasStoreContext((s) => Object.values(s.nodes).some((node) => node.preMaximizeOrigin != null))
   // Idle cursor reflects the active tool (React owns idle; useCanvasInteraction
   // overrides to 'grabbing' during an active pan and hands control back on release).
   const handToolActive = useUIStore((s) => s.activeTool === 'hand')
@@ -313,7 +312,6 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
     if (!el) return
 
     const onWheel = (e: WheelEvent) => {
-      if ((e.target as Element).closest('[data-canvas-maximized="true"]')) return
       handleWheelRef.current(e as unknown as React.WheelEvent<HTMLDivElement>)
     }
 
@@ -369,19 +367,7 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
 
     let prevRect = el.getBoundingClientRect()
     let prevWindowWidth = window.innerWidth
-    let wasMaximized = Object.values(canvasApi.getState().nodes).some((node) => node.preMaximizeOrigin != null)
-
     const observer = new ResizeObserver((entries) => {
-      const maximized = Object.values(canvasApi.getState().nodes).some((node) => node.preMaximizeOrigin != null)
-      const leavingMaximize = wasMaximized && !maximized
-      wasMaximized = maximized
-      // Maximizing changes layout ancestry, not the saved canvas viewport.
-      // Ignore those measurements and do not pan when restoring the layout.
-      if (maximized) {
-        prevRect = el.getBoundingClientRect()
-        prevWindowWidth = window.innerWidth
-        return
-      }
       for (const entry of entries) {
         const size = {
           width: entry.contentRect.width,
@@ -404,7 +390,7 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
       // structural jumps: only compensate when the right edge moved by less than
       // a quarter of the pane width.
       const structuralJump = Math.abs(dRight) > rect.width * 0.25
-      if (!leavingMaximize && !windowResized && !structuralJump && Math.abs(dLeft) < 0.5 && Math.abs(dRight) > 0.5) {
+      if (!windowResized && !structuralJump && Math.abs(dLeft) < 0.5 && Math.abs(dRight) > 0.5) {
         const { viewportOffset } = canvasApi.getState()
         canvasApi.setState({ viewportOffset: { x: viewportOffset.x + dRight, y: viewportOffset.y } })
       }
@@ -724,7 +710,7 @@ const Canvas: React.FC<CanvasProps> = ({ children, overlayChildren, onCreateAtPo
         <div
           ref={topOverlayRef}
           data-canvas-top-overlay={panelId ?? ''}
-          hidden={showSettings || hasMaximizedNode}
+          hidden={showSettings}
           style={{
             position: 'fixed',
             overflow: 'clip',
diff --git a/src/renderer/canvas/CanvasNode.dragPreview.test.tsx b/src/renderer/canvas/CanvasNode.dragPreview.test.tsx
new file mode 100644
index 00000000..f7f804d7
--- /dev/null
+++ b/src/renderer/canvas/CanvasNode.dragPreview.test.tsx
@@ -0,0 +1,148 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+vi.mock('../lib/terminal/terminalRegistry', () => ({
+  terminalRegistry: {
+    release: vi.fn(),
+    dispose: vi.fn(),
+    disposeWorkspace: vi.fn(),
+    has: () => false,
+    getEntry: () => undefined,
+  },
+}))
+
+vi.mock('../stores/useWorktrees', () => ({ useWorktrees: () => [] }))
+
+import * as React from 'react'
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import type { StoreApi } from 'zustand'
+import type { PanelType, Point, Size, WindowDockState } from '../../shared/types'
+import CanvasNode from './CanvasNode'
+import DragOverlay from '../drag/Overlay'
+import { useDragStore } from '../drag'
+import { INITIAL_DRAG_STATE, type DragState } from '../drag/types'
+import { CanvasStoreProvider } from '../stores/CanvasStoreContext'
+import { createCanvasStore, type CanvasStore } from '../stores/canvasStore'
+import { createDefaultDockState, createDockStore } from '../stores/dockStore'
+import { useAppStore } from '../stores/appStore'
+
+;(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+function addNode(
+  store: StoreApi<CanvasStore>,
+  id: string,
+  panelId: string,
+  panelType: PanelType,
+  origin: Point,
+  size: Size,
+) {
+  const created = store.getState().addNode(panelId, panelType, origin, size)
+  store.setState((state) => {
+    const node = state.nodes[created]
+    if (!node) return state
+    const nodes = { ...state.nodes }
+    delete nodes[created]
+    nodes[id] = { ...node, id, origin, size, animationState: 'idle' }
+    return { nodes }
+  })
+}
+
+function renderNode(panelType: 'terminal' | 'browser') {
+  const panelId = `${panelType}-panel`
+  const workspaceId = useAppStore.getState().addWorkspace('WS', '/tmp/ws', `ws-${panelType}`)
+  useAppStore.getState().addPanel(workspaceId, {
+    id: panelId,
+    type: panelType,
+    title: panelType,
+    isDirty: false,
+  })
+
+  const canvasStore = createCanvasStore()
+  canvasStore.getState().setZoomAndOffset(1, { x: 0, y: 0 })
+  addNode(canvasStore, 'node', panelId, panelType, { x: 100, y: 100 }, { width: 300, height: 200 })
+  const zones: WindowDockState = {
+    ...createDefaultDockState(),
+    center: {
+      position: 'center',
+      visible: true,
+      size: 0,
+      layout: { type: 'tabs', id: 'stack', panelIds: [panelId], activeIndex: 0 },
+    },
+  }
+  const dockStore = createDockStore({ zones })
+
+  act(() => root.render(
+    <CanvasStoreProvider store={canvasStore}>
+      <CanvasNode
+        nodeId="node"
+        isFocused
+        dockStoreApi={dockStore}
+        renderPanel={() => panelType === 'browser'
+          ? React.createElement('webview', { 'data-panel-surface': panelType })
+          : <div data-panel-surface={panelType}>terminal output</div>}
+      />
+      <DragOverlay />
+    </CanvasStoreProvider>,
+  ))
+
+  return { canvasStore, panelId }
+}
+
+function startDrag(
+  canvasStore: StoreApi<CanvasStore>,
+  panelId: string,
+  panelType: 'terminal' | 'browser',
+  target: DragState['target'],
+) {
+  act(() => useDragStore.getState().applyDragState({
+    ...INITIAL_DRAG_STATE,
+    isDragging: true,
+    source: {
+      panelId,
+      origin: { kind: 'canvas-node', canvasStoreApi: canvasStore, nodeId: 'node' },
+    },
+    panel: { id: panelId, type: panelType, title: panelType },
+    grab: { x: 20, y: 10 },
+    ghostSize: { width: 300, height: 200 },
+    cursor: { client: { x: 200, y: 170 }, screen: { x: 200, y: 170 }, insideWindow: true },
+    target,
+  }))
+}
+
+beforeEach(() => {
+  vi.stubGlobal('ResizeObserver', class { observe() {} disconnect() {} })
+  useAppStore.setState({ workspaces: [], selectedWorkspaceId: '' })
+  useDragStore.getState().applyDragState(INITIAL_DRAG_STATE)
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => { root = createRoot(container) })
+})
+
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  useDragStore.getState().applyDragState(INITIAL_DRAG_STATE)
+  vi.unstubAllGlobals()
+})
+
+describe('CanvasNode drag preview', () => {
+  it.each(['terminal', 'browser'] as const)('hides the live %s surface and always renders the ghost', (panelType) => {
+    const { canvasStore, panelId } = renderNode(panelType)
+    startDrag(canvasStore, panelId, panelType, {
+      kind: 'canvas-reposition',
+      canvasStoreApi: canvasStore,
+      nodeId: 'node',
+      origin: { x: 180, y: 160 },
+    })
+
+    const node = container.querySelector<HTMLElement>('[data-node-id="node"]')!
+    expect(node.style.left).toBe('100px')
+    expect(node.style.top).toBe('100px')
+    expect(node.style.visibility).toBe('hidden')
+    expect(node.querySelector(`[data-panel-surface="${panelType}"]`)).not.toBeNull()
+    expect(document.querySelector('[data-drag-overlay-ghost="true"]')).not.toBeNull()
+  })
+})
diff --git a/src/renderer/canvas/CanvasNode.groupDrag.test.tsx b/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
index 2ca525c9..c5e05e97 100644
--- a/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
+++ b/src/renderer/canvas/CanvasNode.groupDrag.test.tsx
@@ -178,6 +178,108 @@ describe('CanvasNode — file drags into an unfocused webview', () => {
   })
 })
 
+it('promotes one tab from a canvas node and restores the full mini-dock while unchanged', () => {
+  const wsId = useAppStore.getState().addWorkspace('WS', '/tmp/ws', 'ws-present')
+  useAppStore.getState().addPanel(wsId, { id: 'canvas', type: 'canvas', title: 'Canvas', isDirty: false })
+  useAppStore.getState().addPanel(wsId, { id: 'editor', type: 'editor', title: 'Editor', isDirty: false })
+  useAppStore.getState().addPanel(wsId, { id: 'sibling', type: 'browser', title: 'Browser', isDirty: false })
+  const canvas = freshCanvasStore()
+  addNode(canvas, 'node', 'editor', { x: 120, y: 230 }, { width: 400, height: 300 })
+  const nodeDock = tabsDockStore('editor')
+  nodeDock.getState().dockPanel('sibling', 'center', { type: 'tab', stackId: 'stack-editor' })
+  nodeDock.getState().setActiveTab('stack-editor', 0)
+  canvas.getState().setNodeDockLayout('node', nodeDock.getState().zones.center.layout)
+  const unsubscribe = nodeDock.subscribe((state, previous) => {
+    const layout = state.zones.center.layout
+    if (layout !== previous.zones.center.layout && layout) canvas.getState().setNodeDockLayout('node', layout)
+  })
+  const outerDock = createDockStore()
+  outerDock.getState().dockPanel('canvas', 'center')
+  const canvasLocation = outerDock.getState().getPanelLocation('canvas')!
+  if (canvasLocation.type !== 'dock') throw new Error('Expected dock location')
+
+  act(() => root.render(
+    <CanvasStoreProvider store={canvas}>
+      <CanvasNode
+        nodeId="node"
+        canvasPanelId="canvas"
+        isFocused
+        dockStoreApi={nodeDock}
+        outerDockStoreApi={outerDock}
+        renderPanel={() => <div />}
+      />
+    </CanvasStoreProvider>,
+  ))
+
+  act(() => container.querySelector<HTMLButtonElement>('[aria-label="Move panel into dock"]')!.click())
+  expect(canvas.getState().nodes.node.dockLayout).toMatchObject({ panelIds: ['sibling'] })
+  expect(outerDock.getState().zones.center.layout).toMatchObject({
+    type: 'tabs', panelIds: ['canvas', 'editor'], activeIndex: 1,
+  })
+  expect(outerDock.getState().canRestorePresentation(canvasLocation.stackId)).toBe(true)
+
+  act(() => { outerDock.getState().restorePresentation(canvasLocation.stackId) })
+  expect(outerDock.getState().zones.center.layout).toMatchObject({ type: 'tabs', panelIds: ['canvas'] })
+  expect(canvas.getState().nodes.node).toMatchObject({
+    origin: { x: 120, y: 230 }, size: { width: 400, height: 300 },
+    dockLayout: { panelIds: ['editor', 'sibling'], activeIndex: 0 },
+  })
+
+  // A later source edit consumes the next reverse transaction permanently.
+  // This covers the multi-panel case where the original canvas node survives
+  // promotion and can itself be tabbed/split while the promoted panel is open.
+  act(() => nodeDock.getState().dockPanel('editor', 'center', {
+    type: 'tab', stackId: 'stack-editor', index: 0,
+  }))
+  act(() => container.querySelector<HTMLButtonElement>('[aria-label="Move panel into dock"]')!.click())
+  expect(outerDock.getState().presentation).not.toBeNull()
+  act(() => nodeDock.getState().dockPanel('changed-source', 'center', {
+    type: 'tab', stackId: 'stack-editor',
+  }))
+  expect(outerDock.getState().presentation).toBeNull()
+  unsubscribe()
+})
+
+it('removes and restores a singleton canvas node when its panel is promoted', () => {
+  const wsId = useAppStore.getState().addWorkspace('WS', '/tmp/ws', 'ws-present-single')
+  useAppStore.getState().addPanel(wsId, { id: 'canvas', type: 'canvas', title: 'Canvas', isDirty: false })
+  useAppStore.getState().addPanel(wsId, { id: 'editor', type: 'editor', title: 'Editor', isDirty: false })
+  const canvas = freshCanvasStore()
+  addNode(canvas, 'node', 'editor', { x: 120, y: 230 }, { width: 400, height: 300 })
+  const nodeDock = tabsDockStore('editor')
+  const outerDock = createDockStore()
+  outerDock.getState().dockPanel('canvas', 'center')
+  const canvasLocation = outerDock.getState().getPanelLocation('canvas')!
+  if (canvasLocation.type !== 'dock') throw new Error('Expected dock location')
+
+  act(() => root.render(
+    <CanvasStoreProvider store={canvas}>
+      <CanvasNode
+        nodeId="node"
+        canvasPanelId="canvas"
+        isFocused
+        dockStoreApi={nodeDock}
+        outerDockStoreApi={outerDock}
+        renderPanel={() => <div />}
+      />
+    </CanvasStoreProvider>,
+  ))
+
+  act(() => container.querySelector<HTMLButtonElement>('[aria-label="Move panel into dock"]')!.click())
+  expect(canvas.getState().nodes.node).toBeUndefined()
+  expect(outerDock.getState().zones.center.layout).toMatchObject({
+    type: 'tabs', panelIds: ['canvas', 'editor'], activeIndex: 1,
+  })
+
+  act(() => { outerDock.getState().restorePresentation(canvasLocation.stackId) })
+  expect(outerDock.getState().zones.center.layout).toMatchObject({ panelIds: ['canvas'] })
+  expect(canvas.getState().nodes.node).toMatchObject({
+    origin: { x: 120, y: 230 },
+    size: { width: 400, height: 300 },
+    dockLayout: { panelIds: ['editor'] },
+  })
+})
+
 describe('CanvasNode — group drag from the title bar', () => {
   it('grabbing a multi-selected node by its tab bar arms a GROUP drag carrying the whole selection', () => {
     const wsId = useAppStore.getState().addWorkspace('WS', '/tmp/ws', 'ws-group-drag')
@@ -335,40 +437,3 @@ describe('CanvasNode — group drag from the title bar', () => {
     expect(store.getState().nodes['B'].origin).toEqual({ x: 400, y: 0 })
   })
 })
-
-it('uses split-sized diagonal maximize controls and restores the live canvas panel', () => {
-  const wsId = useAppStore.getState().addWorkspace('WS', '/tmp/ws', 'ws-maximize')
-  useAppStore.getState().addPanel(wsId, { id: 'panel-A', type: 'editor', title: 'Editor', isDirty: false })
-  const store = freshCanvasStore()
-  addNode(store, 'A', 'panel-A', { x: 120, y: 230 }, { width: 400, height: 300 })
-  const dock = tabsDockStore('panel-A')
-  act(() => root.render(
-    <CanvasStoreProvider store={store}>
-      <CanvasNode nodeId="A" isFocused dockStoreApi={dock} renderPanel={() => <input defaultValue="keep" />} />
-    </CanvasStoreProvider>,
-  ))
-  const node = container.querySelector<HTMLElement>('[data-node-id="A"]')!
-  const input = node.querySelector('input')
-  expect(node.querySelector('.dock-tab-bar')?.classList.contains('min-h-[26px]')).toBe(true)
-  const button = container.querySelector<HTMLButtonElement>('[aria-label="Maximize"]')!
-  expect(button.classList.contains('w-[22px]')).toBe(true)
-  expect(button.querySelector('.lucide-maximize2')).not.toBeNull()
-  expect(button.querySelector('svg')?.getAttribute('width')).toBe('12')
-  act(() => button.click())
-  expect(node.style.position).toBe('absolute')
-  expect(node.style.width).toBe('100%')
-  expect(node.style.height).toBe('100%')
-  expect(container.querySelector('[data-resize-frame-for]')).toBeNull()
-  const restore = container.querySelector<HTMLButtonElement>('[aria-label="Restore"]')!
-  expect(restore.querySelector('.lucide-minimize2')).not.toBeNull()
-  expect(restore.classList.contains('w-6')).toBe(true)
-  expect(restore.querySelector('svg')?.getAttribute('width')).toBe('14')
-  expect(node.querySelector('.dock-tab-bar')?.classList.contains('app-header-bar')).toBe(true)
-  act(() => restore.click())
-  expect(node.style.position).toBe('absolute')
-  expect(node.style.left).toBe('120px')
-  expect(node.style.top).toBe('230px')
-  expect(node.style.width).toBe('400px')
-  expect(node.querySelector('input')).toBe(input)
-  expect(node.querySelector('.dock-tab-bar')?.classList.contains('min-h-[26px]')).toBe(true)
-})
diff --git a/src/renderer/canvas/CanvasNode.tsx b/src/renderer/canvas/CanvasNode.tsx
index 11ca4537..55c2d6ea 100644
--- a/src/renderer/canvas/CanvasNode.tsx
+++ b/src/renderer/canvas/CanvasNode.tsx
@@ -11,8 +11,7 @@ import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { useRenderCount } from '../lib/perf/perfClient'
 import type { StoreApi } from 'zustand'
-import type { NodeActivityState, DockTabStack as DockTabStackNode, PanelType } from '../../shared/types'
-import { isMaximized as checkMaximized } from '../../shared/types'
+import type { NodeActivityState, DockLayoutNode, DockTabStack as DockTabStackNode, PanelType } from '../../shared/types'
 import { useCanvasStoreContext, useCanvasStoreApi } from '../stores/CanvasStoreContext'
 import { useAppStore, useSelectedWorkspace } from '../stores/appStore'
 import { useUIStore } from '../stores/uiStore'
@@ -23,7 +22,7 @@ import { useCanvasNodeDrag } from './useCanvasNodeDrag'
 import { isSelected as isNodeSelected, isGroupDragMember } from '../stores/canvas/selectionModel'
 import { useNodeResizeCursor } from './useNodeResizeCursor'
 import { NodeResizeOverlay } from './NodeResizeOverlay'
-import type { DockStore } from '../stores/dockStore'
+import { removePanelFromTree, type DockStore } from '../stores/dockStore'
 import { DockStoreProvider } from '../stores/DockStoreContext'
 import DockTabStack from '../docking/DockTabStack'
 import { activeLeafPanelId } from '../panels/nodeDockRegistry'
@@ -33,7 +32,7 @@ import { Tooltip } from '../ui/Tooltip'
 import DockLayoutRenderer from '../docking/DockLayoutRenderer'
 import { confirmClosePanels } from '../lib/confirmClosePanels'
 import { collectPanelIds } from '../../shared/collectPanelIds'
-import { Maximize2, Minimize2, X, Lock, LockOpen } from 'lucide-react'
+import { X, Lock, LockOpen } from 'lucide-react'
 import { PANEL_DEFINITIONS } from '../../shared/panels'
 import { captureRendererException } from '../lib/sentry'
 import { useCanvasTopOverlayTarget } from './CanvasTopOverlayContext'
@@ -58,10 +57,13 @@ function handToolPanShouldWin(e: React.MouseEvent): boolean {
 
 export interface CanvasNodeProps {
   nodeId: string
+  canvasPanelId?: string
   isFocused: boolean
   activityState?: NodeActivityState
   /** Per-node DockStore that owns the layout for this node. Created in CanvasPanel. */
   dockStoreApi: StoreApi<DockStore>
+  /** Dock store which owns the canvas panel containing this node. */
+  outerDockStoreApi?: StoreApi<DockStore>
   /** Render the panel content for a given panelId. */
   renderPanel: (panelId: string) => React.ReactNode
   /** Title used in tooltips / context when there's no dock panel. */
@@ -79,6 +81,21 @@ const CANVAS_EXCLUDED_TYPES = (Object.values(PANEL_DEFINITIONS)
   .filter((definition) => !definition.canLiveOnCanvas)
   .map((definition) => definition.type)) satisfies PanelType[]
 
+function sameDockTopology(a: DockLayoutNode | null, b: DockLayoutNode | null): boolean {
+  if (!a || !b) return a === b
+  if (a.type !== b.type || a.id !== b.id) return false
+  if (a.type === 'tabs' && b.type === 'tabs') {
+    return a.panelIds.length === b.panelIds.length
+      && a.panelIds.every((panelId, index) => panelId === b.panelIds[index])
+  }
+  if (a.type === 'split' && b.type === 'split') {
+    return a.direction === b.direction
+      && a.children.length === b.children.length
+      && a.children.every((child, index) => sameDockTopology(child, b.children[index]))
+  }
+  return false
+}
+
 // -----------------------------------------------------------------------------
 // Pulse animation keyframes (injected once)
 // -----------------------------------------------------------------------------
@@ -98,35 +115,6 @@ const PULSE_KEYFRAMES = `
   opacity: 0 !important;
   pointer-events: none !important;
 }
-/* The shell excludes the workspace sidebars and spans every dock split.
-   Keep panel contents mounted while the shell becomes its containing block. */
-[data-panel-maximize-root] :has([data-canvas-maximized="true"]) {
-  position: static !important;
-  transform: none !important;
-  filter: none !important;
-  perspective: none !important;
-  contain: none !important;
-  will-change: auto !important;
-  overflow: visible !important;
-  z-index: auto !important;
-}
-[data-canvas-maximized="true"] { --zoom: 1; }
-[data-canvas-container]:has([data-canvas-maximized="true"]) {
-  position: absolute !important;
-  inset: 0;
-  width: 100% !important;
-  height: 100% !important;
-  overflow: clip !important;
-}
-[data-dock-stack-id]:has([data-canvas-maximized="true"]) > .dock-tab-bar {
-  display: none;
-}
-/* Hide sibling branches along the path to the maximized panel. This also
-   hides persistent browser slots in other splits without unmounting them. */
-[data-panel-maximize-root]:has([data-canvas-maximized="true"]) > :not(:has([data-canvas-maximized="true"])):not([data-canvas-maximized="true"]),
-[data-panel-maximize-root] :has([data-canvas-maximized="true"]) > :not(:has([data-canvas-maximized="true"])):not([data-canvas-maximized="true"]) {
-  visibility: hidden;
-}
 `
 
 let keyframesInjected = false
@@ -184,9 +172,11 @@ function GrabButton({
 
 const CanvasNode: React.FC<CanvasNodeProps> = ({
   nodeId,
+  canvasPanelId,
   isFocused,
   activityState,
   dockStoreApi,
+  outerDockStoreApi,
   renderPanel,
   title: _title = 'Panel',
 }) => {
@@ -194,6 +184,18 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
   useRenderCount('CanvasNode')
 
   const canvasApi = useCanvasStoreApi()
+  const [outerPresentationActive, setOuterPresentationActive] = useState(
+    () => !!outerDockStoreApi?.getState().presentation,
+  )
+  useEffect(() => {
+    if (!outerDockStoreApi) return
+    setOuterPresentationActive(!!outerDockStoreApi.getState().presentation)
+    return outerDockStoreApi.subscribe((state, previous) => {
+      if (!!state.presentation !== !!previous.presentation) {
+        setOuterPresentationActive(!!state.presentation)
+      }
+    })
+  }, [outerDockStoreApi])
   const topOverlayTarget = useCanvasTopOverlayTarget()
   const nodeRef = useRef<HTMLDivElement>(null)
   const [isHovered, setIsHovered] = useState(false)
@@ -241,7 +243,6 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
   )
   const focusNode = useCanvasStoreContext((s) => s.focusNode)
   const removeNode = useCanvasStoreContext((s) => s.removeNode)
-  const toggleMaximize = useCanvasStoreContext((s) => s.toggleMaximize)
   const isSelected = useCanvasStoreContext((s) => isNodeSelected(s, nodeId))
   const isDockDragging = useDragStore((s) => s.isDragging)
   const { hidden: isWholeNodeDragSource } = useDragSourceVisibility(nodeId)
@@ -278,8 +279,6 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
     handleDragStart(e)
   }, [handleDragStart, handleTabDetachStart, dockStoreApi, canvasApi, nodeId])
 
-  const maximized = node ? checkMaximized(node) : false
-
   const { handleResizeStart } = useNodeResize(nodeId, primaryPanelType, canvasApi)
   // Under the Hand tool, edge presses pan instead of resizing.
   const handleResizeStartGuarded = useCallback(
@@ -390,40 +389,74 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
     removeNode(nodeId)
   }, [removeNode, nodeId, layout, confirmCloseForPanels, wsId])
 
-  const handleToggleMaximize = useCallback(() => {
-    const viewportSize = { width: window.innerWidth, height: window.innerHeight }
-    toggleMaximize(nodeId, viewportSize)
-  }, [toggleMaximize, nodeId])
-
-  // Spring-load: when ANY dock drag is active AND this node is maximized
-  // (covering the canvas), un-maximize after a short delay so the user can
-  // see the canvas underneath and target a drop point.
-  const toggleMaximizeRef = useRef(handleToggleMaximize)
-  toggleMaximizeRef.current = handleToggleMaximize
-  const maximizedRef = useRef(maximized)
-  maximizedRef.current = maximized
-  useEffect(() => {
-    let timerId: number | null = null
-    const tryArm = () => {
-      const s = useDragStore.getState()
-      if (!s.isDragging || s.panel?.type === 'canvas') return
-      if (!maximizedRef.current) return
-      if (timerId !== null) return
-      timerId = window.setTimeout(() => {
-        timerId = null
-        if (maximizedRef.current) toggleMaximizeRef.current()
-      }, 200)
-    }
-    const cancel = () => {
-      if (timerId !== null) { window.clearTimeout(timerId); timerId = null }
+  const handlePresentPanel = useCallback((panelId: string) => {
+    if (!outerDockStoreApi || !canvasPanelId) return
+    const outer = outerDockStoreApi.getState()
+    if (outer.presentation) return
+    const canvasLocation = outer.getPanelLocation(canvasPanelId)
+    if (!canvasLocation || canvasLocation.type !== 'dock') return
+    const restoreLayout = outer.zones[canvasLocation.zone].layout
+    const sourceNode = canvasApi.getState().nodes[nodeId]
+    const sourceLayout = dockStoreApi.getState().zones.center.layout
+    if (!restoreLayout || !sourceNode || !sourceLayout || !collectPanelIds(sourceLayout).includes(panelId)) return
+
+    const expectedSourceLayout = removePanelFromTree(sourceLayout, panelId)
+    dockStoreApi.getState().undockPanel(panelId)
+    if (!expectedSourceLayout) canvasApi.getState().finalizeRemoveNode(nodeId)
+
+    outerDockStoreApi.getState().dockPanel(panelId, canvasLocation.zone, {
+      type: 'tab',
+      stackId: canvasLocation.stackId,
+    })
+    const expectedLayout = outerDockStoreApi.getState().zones[canvasLocation.zone].layout
+    if (!expectedLayout) return
+
+    let unsubscribeSource = () => {}
+    const presentation = {
+      stackId: canvasLocation.stackId,
+      panelId,
+      zone: canvasLocation.zone,
+      restoreLayout,
+      expectedLayout,
+      canRestoreExternal: () => {
+        const current = canvasApi.getState().nodes[nodeId]
+        return expectedSourceLayout
+          ? !!current && sameDockTopology(current.dockLayout, expectedSourceLayout)
+          : !current
+      },
+      restoreExternal: () => {
+        // The canvas panel is normally unmounted while its promoted sibling is
+        // active, so its per-node DockStore may no longer be registered. Restore
+        // the persisted canvas projection directly; remount will seed the live
+        // mini-dock from this exact layout.
+        canvasApi.setState((state) => ({
+          nodes: {
+            ...state.nodes,
+            [nodeId]: {
+              ...(state.nodes[nodeId] ?? sourceNode),
+              dockLayout: sourceLayout,
+              animationState: 'idle',
+            },
+          },
+          selection: [nodeId],
+          selectionActive: true,
+          focusEpoch: state.focusEpoch + 1,
+        }))
+        setActivePanel(canvasPanelId)
+      },
+      dispose: () => unsubscribeSource(),
     }
-    tryArm()
-    const unsub = useDragStore.subscribe((s, prev) => {
-      if (s.isDragging && !prev.isDragging) tryArm()
-      else if (!s.isDragging && prev.isDragging) cancel()
+    outerDockStoreApi.getState().beginPresentation(presentation)
+    unsubscribeSource = canvasApi.subscribe(() => {
+      const current = outerDockStoreApi.getState().presentation
+      if (current !== presentation) {
+        unsubscribeSource()
+        return
+      }
+      if (!presentation.canRestoreExternal()) outerDockStoreApi.getState().discardPresentation()
     })
-    return () => { cancel(); unsub() }
-  }, [])
+    setActivePanel(panelId)
+  }, [outerDockStoreApi, canvasPanelId, canvasApi, nodeId, dockStoreApi])
 
   const handleTogglePin = useCallback(() => {
     canvasApi.getState().togglePin(nodeId)
@@ -468,11 +501,11 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
     return () => canvasApi.getState().setNodeActiveWorktree(nodeId, null)
   }, [nodeId, canvasApi])
 
-  const tabIconSize = maximized ? 14 : 12
+  const tabIconSize = 12
   const nodeControlButtons = (
     <>
       <GrabButton
-        compact={!maximized}
+        compact
         title={node?.isPinned ? 'Unlock' : 'Lock'}
         onClick={(e) => { e.stopPropagation(); handleTogglePin() }}
         color={node?.isPinned ? 'var(--focus-blue)' : undefined}
@@ -482,16 +515,7 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
           : <LockOpen size={tabIconSize} />}
       </GrabButton>
       <GrabButton
-        compact={!maximized}
-        title={maximized ? 'Restore' : 'Maximize'}
-        onClick={(e) => { e.stopPropagation(); handleToggleMaximize() }}
-      >
-        {maximized
-          ? <Minimize2 size={tabIconSize} />
-          : <Maximize2 size={tabIconSize} />}
-      </GrabButton>
-      <GrabButton
-        compact={!maximized}
+        compact
         title="Close"
         onClick={(e) => { e.stopPropagation(); handleClose() }}
       >
@@ -516,7 +540,8 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
           onPanelRemoved={handlePanelRemoved}
           excludePanelTypes={CANVAS_EXCLUDED_TYPES}
           localOnly
-          compact={!maximized}
+          compact
+          onPresentPanel={outerDockStoreApi && canvasPanelId && !outerPresentationActive ? handlePresentPanel : undefined}
           onTabBarMouseDown={isHeaderHost ? handleHeaderMouseDown : undefined}
           trailingControls={isHeaderHost ? nodeControlButtons : undefined}
           dropDisabled={isWholeNodeDragSource}
@@ -633,13 +658,14 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
       const target = e.target as HTMLElement
       if (target.closest('[data-grab-button]')) return
       e.stopPropagation()
-      if (e.detail === 2) {
-        handleToggleMaximize()
+      if (e.detail === 2 && !outerPresentationActive) {
+        const panelId = activeLeafPanelId(dockStoreApi.getState().zones.center.layout)
+        if (panelId) handlePresentPanel(panelId)
         return
       }
       handleDragStart(e)
     },
-    [handleDragStart, handleToggleMaximize],
+    [handleDragStart, handlePresentPanel, dockStoreApi, outerPresentationActive],
   )
 
   const handleGrabStripContextMenu = useCallback(
@@ -648,7 +674,7 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
       e.stopPropagation()
       if (!window.electronAPI) return
       const id = await window.electronAPI.showContextMenu([
-        { id: 'maximize', label: maximized ? 'Restore' : 'Maximize' },
+        ...(!outerPresentationActive ? [{ id: 'maximize', label: 'Move into Dock' }] : []),
         { id: 'pin', label: node?.isPinned ? 'Unlock' : 'Lock' },
         { type: 'separator' },
         { id: 'front', label: 'Move to Front' },
@@ -657,14 +683,18 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
         { id: 'close', label: 'Close', accelerator: 'Cmd+W' },
       ])
       switch (id) {
-        case 'maximize': handleToggleMaximize(); break
+        case 'maximize': {
+          const panelId = activeLeafPanelId(dockStoreApi.getState().zones.center.layout)
+          if (panelId) handlePresentPanel(panelId)
+          break
+        }
         case 'pin': handleTogglePin(); break
         case 'front': canvasApi.getState().moveToFront(nodeId); break
         case 'back': canvasApi.getState().moveToBack(nodeId); break
         case 'close': handleClose(); break
       }
     },
-    [maximized, node?.isPinned, handleToggleMaximize, handleTogglePin, handleClose, canvasApi, nodeId],
+    [node?.isPinned, handlePresentPanel, handleTogglePin, handleClose, canvasApi, dockStoreApi, nodeId, outerPresentationActive],
   )
 
   // --- Computed styles -------------------------------------------------------
@@ -707,7 +737,6 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
     <div
       ref={nodeRef}
       data-node-id={nodeId}
-      data-canvas-maximized={maximized ? "true" : undefined}
       data-node-active={isFocused ? 'true' : 'false'}
       style={containerStyle}
       onClick={handleClick}
@@ -859,7 +888,7 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
         Mounted as a sibling (not inside the node's overflow:hidden box) so the
         strips can overhang the edge; positioned to the node's bounds and
         stacked with it. */}
-    {!maximized && !isWholeNodeDragSource && (
+    {!isWholeNodeDragSource && (
       <div
         aria-hidden
         data-resize-frame-for={nodeId}
@@ -883,9 +912,11 @@ const CanvasNode: React.FC<CanvasNodeProps> = ({
 export default React.memo(CanvasNode, (prev, next) => {
   return (
     prev.nodeId === next.nodeId &&
+    prev.canvasPanelId === next.canvasPanelId &&
     prev.isFocused === next.isFocused &&
     prev.activityState === next.activityState &&
     prev.dockStoreApi === next.dockStoreApi &&
+    prev.outerDockStoreApi === next.outerDockStoreApi &&
     prev.renderPanel === next.renderPanel &&
     prev.title === next.title
   )
diff --git a/src/renderer/canvas/CanvasToolbar.test.ts b/src/renderer/canvas/CanvasToolbar.test.ts
index 2ff829c1..51d2ec9d 100644
--- a/src/renderer/canvas/CanvasToolbar.test.ts
+++ b/src/renderer/canvas/CanvasToolbar.test.ts
@@ -36,12 +36,14 @@ describe('CanvasToolbar — minimap section', () => {
     expect(SOURCE).not.toMatch(/\{showMinimap && \(/)
   })
 
-  it('collapses from measured overlap and expands vertically from the bottom-right', () => {
+  it('collapses from measured overlap and keeps compact actions left of a bottom-right minimap', () => {
     expect(SOURCE).toContain('horizontalCardRef.current')
     expect(SOURCE).toContain('shrink-0 w-max pointer-events-auto')
     expect(SOURCE).toContain('centeredRight <= areaWidth - bottomRightInset')
     expect(SOURCE).toContain('className="absolute bottom-4 z-50 pointer-events-none"')
-    expect(SOURCE).toContain("style={{ right: '1rem' }}")
+    expect(SOURCE).toContain('const compactToolbarRight = mmBottom && mmRight ? 16 + minimapWidth + 8 : 16')
+    expect(SOURCE).toContain('style={{ right: compactToolbarRight }}')
+    expect(SOURCE).toContain("...(mmRight ? { right: '1rem' } : { left: '1rem' })")
     expect(SOURCE).toContain('card.isConnected && card.offsetWidth > 0')
     expect(SOURCE).not.toContain('onMouseEnter={() => setHovered(true)}')
   })
diff --git a/src/renderer/canvas/CanvasToolbar.tsx b/src/renderer/canvas/CanvasToolbar.tsx
index 9b92b94d..1d3e0d79 100644
--- a/src/renderer/canvas/CanvasToolbar.tsx
+++ b/src/renderer/canvas/CanvasToolbar.tsx
@@ -191,6 +191,7 @@ const CanvasToolbar: React.FC<CanvasToolbarProps> = ({
   const minimapWidth = minimapOpen ? 220 : 44
   const bottomLeftInset = mmBottom && !mmRight ? 16 + minimapWidth + 8 : 16
   const bottomRightInset = mmBottom && mmRight ? 16 + minimapWidth + 8 : 16
+  const compactToolbarRight = mmBottom && mmRight ? 16 + minimapWidth + 8 : 16
   const centeredLeft = (areaWidth - toolbarWidth) / 2
   const centeredRight = centeredLeft + toolbarWidth
   const isHorizontal = areaWidth === 0 || toolbarWidth === 0 || (
@@ -358,11 +359,11 @@ const CanvasToolbar: React.FC<CanvasToolbarProps> = ({
       </div>
     ) : (
       /* Narrow canvas: one bottom-right button expands the toolbar upward. If
-         the minimap occupies that corner, keep the button directly beside it. */
+         the minimap occupies that corner, keep the actions directly left of it. */
       <div
         ref={wrapperRef}
         className="absolute bottom-4 z-50 pointer-events-none"
-        style={{ right: '1rem' }}
+        style={{ right: compactToolbarRight }}
       >
         <div
           data-onboarding="toolbar"
@@ -417,7 +418,7 @@ const CanvasToolbar: React.FC<CanvasToolbarProps> = ({
       className="absolute z-50 flex gap-2 pointer-events-auto"
       style={{
         ...(mmBottom ? { bottom: '1rem' } : { top: '1rem' }),
-        ...(mmRight ? { right: !isHorizontal && mmBottom ? 'calc(1rem + 52px)' : '1rem' } : { left: '1rem' }),
+        ...(mmRight ? { right: '1rem' } : { left: '1rem' }),
         flexDirection: mmRight ? 'row' : 'row-reverse',
         alignItems: mmBottom ? 'flex-end' : 'flex-start',
       }}
diff --git a/src/renderer/canvas/RecentScreenshotButton.test.tsx b/src/renderer/canvas/RecentScreenshotButton.test.tsx
index cd8bdfd9..be4e631e 100644
--- a/src/renderer/canvas/RecentScreenshotButton.test.tsx
+++ b/src/renderer/canvas/RecentScreenshotButton.test.tsx
@@ -85,12 +85,11 @@ it('opens clicked screenshots, navigates with overlay controls and keys, and clo
     naturalHeight = nextImageHeight
     decode = async () => {}
   })
-  const originalBytes = new Uint8Array([137, 80, 78, 71]).buffer
   const shots = ['first', 'second', 'third'].map(id => ({ id, filePath: `/${id}.png`, dataUrl: `data:image/png;base64,${id}` }))
   window.electronAPI = {
     ...originalAPI,
     getRecentScreenshot: vi.fn().mockResolvedValue(shots),
-    fsReadBinary: vi.fn().mockResolvedValue(originalBytes),
+    readRecentScreenshot: vi.fn().mockResolvedValue('data:image/png;base64,iVBORw=='),
     shellOpenPath: vi.fn().mockResolvedValue({ ok: true }),
     onRecentScreenshotChanged: vi.fn(() => () => {}),
     dragRecentScreenshot: vi.fn().mockResolvedValue(undefined),
@@ -101,7 +100,7 @@ it('opens clicked screenshots, navigates with overlay controls and keys, and clo
   const dialog = () => document.querySelector('[role="dialog"]')!
   const key = (value: string) => act(async () => document.activeElement!.dispatchEvent(new KeyboardEvent('keydown', { key: value, bubbles: true })))
   const expectOriginal = (index: number) => {
-    expect(window.electronAPI.fsReadBinary).toHaveBeenLastCalledWith(shots[index].filePath)
+    expect(window.electronAPI.readRecentScreenshot).toHaveBeenLastCalledWith(shots[index].id)
     expect(dialog().querySelector('img')?.getAttribute('src')).toBe('data:image/png;base64,iVBORw==')
   }
   try {
@@ -111,6 +110,7 @@ it('opens clicked screenshots, navigates with overlay controls and keys, and clo
     await act(async () => thumbnail.click())
     expectOriginal(1)
     expect(dialog().contains(document.activeElement)).toBe(true)
+    expect(dialog().querySelector('[aria-label="Annotate screenshot"]')).not.toBeNull()
     nextImageWidth = 4000
     nextImageHeight = 100
     await key('ArrowRight')
@@ -130,12 +130,19 @@ it('opens clicked screenshots, navigates with overlay controls and keys, and clo
     await act(async () => (dialog().querySelector('[aria-label="Previous screenshot"]') as HTMLButtonElement).click())
     expectOriginal(1)
     await key('Tab')
-    expect(document.activeElement?.getAttribute('aria-label')).toBe('Edit screenshot')
+    expect(document.activeElement?.getAttribute('aria-label')).toBe('Draw with pen')
     expect(dialog().querySelector('img')?.className).toContain('rounded-xl')
-    await act(async () => (dialog().querySelector('[aria-label="Edit screenshot"]') as HTMLButtonElement).click())
     expect(window.electronAPI.shellOpenPath).not.toHaveBeenCalled()
-    expect(dialog().querySelector('[aria-label="Draw on screenshot"]')).not.toBeNull()
-    await act(async () => (dialog().querySelector('[aria-label="Edit screenshot"]') as HTMLButtonElement).click())
+    expect(dialog().querySelector('[aria-label="Annotate screenshot"]')).not.toBeNull()
+    await act(async () => (dialog().querySelector('[aria-label="Add comment"]') as HTMLButtonElement).click())
+    const annotation = dialog().querySelector('[aria-label="Annotate screenshot"]') as SVGSVGElement
+    annotation.getBoundingClientRect = () => ({ x: 0, y: 0, left: 0, top: 0, right: 800, bottom: 600, width: 800, height: 600, toJSON: () => ({}) })
+    await act(async () => annotation.dispatchEvent(new MouseEvent('click', { clientX: 400, clientY: 300, bubbles: true })))
+    const comment = dialog().querySelector('[aria-label="Comment 1"]') as HTMLTextAreaElement
+    expect(comment).not.toBeNull()
+    const caretKey = new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true, cancelable: true })
+    await act(async () => comment.dispatchEvent(caretKey))
+    expect(caretKey.defaultPrevented).toBe(false)
     expect(dialog().querySelector('[aria-label="Download screenshot"]')?.getAttribute('href')).toBe('data:image/png;base64,iVBORw==')
     expect(dialog().querySelector('[aria-label="Download screenshot"]')?.getAttribute('download')).toBe('second.png')
     await act(async () => (dialog().querySelector('[aria-label="Zoom in"]') as HTMLButtonElement).click())
diff --git a/src/renderer/canvas/RecentScreenshotButton.tsx b/src/renderer/canvas/RecentScreenshotButton.tsx
index 49a3024c..eeb79afa 100644
--- a/src/renderer/canvas/RecentScreenshotButton.tsx
+++ b/src/renderer/canvas/RecentScreenshotButton.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
-import { CaretLeft, CaretRight, DownloadSimple, Minus, PencilSimple, Plus, X } from '@phosphor-icons/react'
+import { CaretLeft, CaretRight, DownloadSimple, Minus, Plus, X } from '@phosphor-icons/react'
 import type { RecentScreenshot } from '../../shared/recentScreenshot'
 import { Tooltip } from '../ui/Tooltip'
 import { createPortal } from 'react-dom'
@@ -17,7 +17,6 @@ function ScreenshotViewer({ screenshots, initialIndex, onClose, onSaved }: {
   const [zoom, setZoom] = useState<number | null>(null)
   const [viewport, setViewport] = useState({ width: window.innerWidth, height: window.innerHeight })
   const [drawingToolbarHost, setDrawingToolbarHost] = useState<HTMLDivElement | null>(null)
-  const [editing, setEditing] = useState(false)
   const [direction, setDirection] = useState(1)
   const scrollRef = useRef<HTMLDivElement>(null)
   useLayoutEffect(() => {
@@ -41,17 +40,20 @@ function ScreenshotViewer({ screenshots, initialIndex, onClose, onSaved }: {
   useEffect(() => {
     let active = true
     setErrorId(null)
-    void window.electronAPI.fsReadBinary(screenshot.filePath).then(async bytes => {
+    const readImage = typeof window.electronAPI.readRecentScreenshot === 'function'
+      ? window.electronAPI.readRecentScreenshot(screenshot.id)
+      : window.electronAPI.fsReadBinary(screenshot.filePath).then(bytes => {
+          const data = new Uint8Array(bytes)
+          let binary = ''
+          for (let offset = 0; offset < data.length; offset += 8192) {
+            binary += String.fromCharCode(...data.subarray(offset, offset + 8192))
+          }
+          const extension = screenshot.filePath.split('.').pop()?.toLowerCase()
+          const format = extension === 'jpg' ? 'jpeg' : extension === 'tif' ? 'tiff' : extension
+          return `data:image/${format || 'png'};base64,${btoa(binary)}`
+        })
+    void readImage.then(async url => {
       if (!active) return
-      // Cate allows data: images, but its content security policy blocks blob: URLs.
-      const data = new Uint8Array(bytes)
-      let binary = ''
-      for (let offset = 0; offset < data.length; offset += 8192) {
-        binary += String.fromCharCode(...data.subarray(offset, offset + 8192))
-      }
-      const extension = screenshot.filePath.split('.').pop()?.toLowerCase()
-      const format = extension === 'jpg' ? 'jpeg' : extension === 'tif' ? 'tiff' : extension
-      const url = `data:image/${format || 'png'};base64,${btoa(binary)}`
       const decoded = new Image()
       decoded.src = url
       await decoded.decode()
@@ -78,22 +80,26 @@ function ScreenshotViewer({ screenshots, initialIndex, onClose, onSaved }: {
   useEffect(() => {
     const onKey = (event: KeyboardEvent) => {
       if (!['ArrowLeft', 'ArrowRight', 'Escape', 'Tab'].includes(event.key)) return
+      const target = event.target
+      const editingText = target instanceof HTMLInputElement
+        || target instanceof HTMLTextAreaElement
+        || (target instanceof HTMLElement && target.isContentEditable)
+      if (editingText && (event.key === 'ArrowLeft' || event.key === 'ArrowRight')) return
       event.preventDefault()
       event.stopImmediatePropagation()
-      if (event.key === 'Escape') { if (editing) setEditing(false); else onClose(); return }
+      if (event.key === 'Escape') { onClose(); return }
       if (event.key === 'Tab') {
         const buttons = Array.from(dialogRef.current?.querySelectorAll<HTMLElement>('button:not(:disabled), a[href]') ?? [])
         const current = buttons.indexOf(document.activeElement as HTMLElement)
         buttons[(current + (event.shiftKey ? -1 : 1) + buttons.length) % buttons.length]?.focus()
         return
       }
-      if (editing) return
       setDirection(event.key === 'ArrowLeft' ? -1 : 1)
       setIndex(current => (current + (event.key === 'ArrowLeft' ? -1 : 1) + screenshots.length) % screenshots.length)
     }
     document.addEventListener('keydown', onKey, true)
     return () => document.removeEventListener('keydown', onKey, true)
-  }, [screenshots.length, onClose, editing])
+  }, [screenshots.length, onClose])
 
   const displayHeight = Math.max(80, viewport.height - 160)
   const fit = image ? Math.min(1, Math.max(1, viewport.width - 96) / image.width, displayHeight / image.height) : 1
@@ -109,9 +115,6 @@ function ScreenshotViewer({ screenshots, initialIndex, onClose, onSaved }: {
         className="flex h-full flex-col outline-none">
         <div ref={setDrawingToolbarHost} className="absolute left-1/2 top-3 z-20 -translate-x-1/2" />
         <div className="absolute right-3 top-3 z-10 flex gap-2" onClick={event => event.stopPropagation()}>
-          <button type="button" aria-label="Edit screenshot" title="Draw on screenshot" className={`${controlClass} backdrop-blur-md`}
-            disabled={!image || image.id !== screenshot.id} aria-pressed={editing}
-            onClick={() => setEditing(value => !value)}><PencilSimple size={18} /></button>
           {image?.id === screenshot.id && <a href={image.url} download={screenshot.filePath.split('/').pop()}
             aria-label="Download screenshot" title="Download screenshot" className={`${controlClass} backdrop-blur-md`}><DownloadSimple size={18} /></a>}
           <button type="button" aria-label="Close screenshot preview" title="Close (Esc)"
@@ -129,9 +132,8 @@ function ScreenshotViewer({ screenshots, initialIndex, onClose, onSaved }: {
                 onClick={event => event.stopPropagation()} onError={() => setErrorId(screenshot.id)} draggable={false}
                 style={{ width: image.width * scale, height: image.height * scale }}
                 className="block max-w-none rounded-xl shadow-2xl" />
-              {editing && <ScreenshotDrawing id={image.id} url={image.url} width={image.width} height={image.height}
-                toolbarHost={drawingToolbarHost} onClose={() => setEditing(false)}
-                onSaved={saved => onSaved(saved)} />}
+              <ScreenshotDrawing key={image.id} id={image.id} url={image.url} width={image.width} height={image.height}
+                toolbarHost={drawingToolbarHost} onClose={onClose} onSaved={saved => onSaved(saved)} />
               </div>
             ) : <p role="status" className="p-4 text-center text-white/70">Loading screenshot...</p>}
           </div>
@@ -140,11 +142,11 @@ function ScreenshotViewer({ screenshots, initialIndex, onClose, onSaved }: {
         <div className="flex h-20 shrink-0 items-center justify-center gap-3">
           <div className="flex items-center gap-1 rounded-full bg-neutral-800/80 p-1 shadow-lg backdrop-blur-md" onClick={event => event.stopPropagation()}>
             <button type="button" aria-label="Previous screenshot" title="Previous screenshot (Left arrow)"
-              className={controlClass} disabled={screenshots.length < 2 || editing}
+              className={controlClass} disabled={screenshots.length < 2}
               onClick={() => { setDirection(-1); setIndex(current => (current - 1 + screenshots.length) % screenshots.length) }}><CaretLeft size={18} /></button>
             <span className="min-w-10 text-center text-xs text-white/80" aria-live="polite">{index + 1} / {screenshots.length}</span>
             <button type="button" aria-label="Next screenshot" title="Next screenshot (Right arrow)"
-              className={controlClass} disabled={screenshots.length < 2 || editing}
+              className={controlClass} disabled={screenshots.length < 2}
               onClick={() => { setDirection(1); setIndex(current => (current + 1) % screenshots.length) }}><CaretRight size={18} /></button>
           </div>
           <div className="flex items-center gap-1 rounded-full bg-neutral-800/80 p-1 shadow-lg backdrop-blur-md" onClick={event => event.stopPropagation()}>
diff --git a/src/renderer/canvas/ScreenshotDrawing.test.tsx b/src/renderer/canvas/ScreenshotDrawing.test.tsx
new file mode 100644
index 00000000..5ebee5e5
--- /dev/null
+++ b/src/renderer/canvas/ScreenshotDrawing.test.tsx
@@ -0,0 +1,61 @@
+import React, { act } from 'react'
+import { createRoot } from 'react-dom/client'
+import { afterEach, expect, it, vi } from 'vitest'
+import { ScreenshotDrawing } from './ScreenshotDrawing'
+
+afterEach(() => vi.unstubAllGlobals())
+
+it('adds an editable speech-bubble comment and composites it into the saved PNG', async () => {
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  vi.stubGlobal('Image', class { src = ''; decode = async () => {} })
+  const context = {
+    drawImage: vi.fn(), beginPath: vi.fn(), moveTo: vi.fn(), lineTo: vi.fn(), quadraticCurveTo: vi.fn(), closePath: vi.fn(),
+    save: vi.fn(), restore: vi.fn(), translate: vi.fn(), rotate: vi.fn(),
+    fill: vi.fn(), stroke: vi.fn(), measureText: vi.fn(() => ({ width: 40 })), fillText: vi.fn(),
+    set lineCap(_value: string) {}, set lineJoin(_value: string) {}, set strokeStyle(_value: string) {},
+    set fillStyle(_value: string) {}, set lineWidth(_value: number) {}, set font(_value: string) {}, set textBaseline(_value: string) {},
+  }
+  const originalGetContext = HTMLCanvasElement.prototype.getContext
+  const originalToDataURL = HTMLCanvasElement.prototype.toDataURL
+  HTMLCanvasElement.prototype.getContext = vi.fn(() => context) as never
+  HTMLCanvasElement.prototype.toDataURL = vi.fn(() => 'data:image/png;base64,annotated')
+  const originalAPI = window.electronAPI
+  const saved = { id: 'saved', filePath: '/desktop/saved.png', dataUrl: 'data:image/png;base64,thumb', annotated: true }
+  window.electronAPI = { ...originalAPI, saveRecentScreenshot: vi.fn().mockResolvedValue(saved) }
+  const host = document.createElement('div')
+  const toolbar = document.createElement('div')
+  document.body.append(host, toolbar)
+  const root = createRoot(host)
+  const onSaved = vi.fn()
+  try {
+    await act(async () => root.render(<ScreenshotDrawing id="shot" url="data:image/png;base64,source" width={800} height={600}
+      toolbarHost={toolbar} onClose={vi.fn()} onSaved={onSaved} />))
+    const svg = host.querySelector('svg')!
+    svg.getBoundingClientRect = () => ({ x: 0, y: 0, left: 0, top: 0, right: 800, bottom: 600, width: 800, height: 600, toJSON: () => ({}) })
+    await act(async () => (toolbar.querySelector('[aria-label="Add comment"]') as HTMLButtonElement).click())
+    await act(async () => svg.dispatchEvent(new MouseEvent('click', { clientX: 400, clientY: 300, bubbles: true })))
+    const input = host.querySelector('[aria-label="Comment 1"]') as HTMLTextAreaElement
+    expect(host.querySelector('[aria-label="Move comment 1"]')).not.toBeNull()
+    expect(host.querySelector('polygon')).toBeNull()
+    expect(host.querySelector('[aria-label="Resize comment 1"] circle')).toBeNull()
+    expect(host.querySelector('[aria-label="Rotate comment 1"] circle')).toBeNull()
+    expect((host.querySelector('[aria-label="Rotate comment 1"]') as SVGGElement).style.cursor).toContain('data:image/svg+xml')
+    expect(host.querySelector('foreignObject > div')?.className).toContain('bg-black/30')
+    await act(async () => {
+      const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value')!.set!
+      setter.call(input, 'Please align this section')
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+    })
+    expect(Number(host.querySelector('foreignObject')?.getAttribute('height'))).toBeLessThan(60)
+    await act(async () => [...toolbar.querySelectorAll('button')].find(button => button.textContent === 'Save')!.click())
+    expect(context.fillText).toHaveBeenCalledWith('Please align this section', expect.any(Number), expect.any(Number), expect.any(Number))
+    expect(window.electronAPI.saveRecentScreenshot).toHaveBeenCalledWith('shot', 'data:image/png;base64,annotated')
+    expect(onSaved).toHaveBeenCalledWith(saved, 'data:image/png;base64,annotated')
+  } finally {
+    await act(async () => root.unmount())
+    host.remove(); toolbar.remove()
+    window.electronAPI = originalAPI
+    HTMLCanvasElement.prototype.getContext = originalGetContext
+    HTMLCanvasElement.prototype.toDataURL = originalToDataURL
+  }
+})
diff --git a/src/renderer/canvas/ScreenshotDrawing.tsx b/src/renderer/canvas/ScreenshotDrawing.tsx
index 620055f7..e246e8cf 100644
--- a/src/renderer/canvas/ScreenshotDrawing.tsx
+++ b/src/renderer/canvas/ScreenshotDrawing.tsx
@@ -1,22 +1,109 @@
-import { useRef, useState, type PointerEvent } from 'react'
+import { useRef, useState } from 'react'
 import type { RecentScreenshot } from '../../shared/recentScreenshot'
 import { createPortal } from 'react-dom'
-import { ArrowCounterClockwise, DownloadSimple } from '@phosphor-icons/react'
+import { ArrowCounterClockwise, ChatCircleText, DotsSix, DownloadSimple, PencilSimple, Trash } from '@phosphor-icons/react'
 
 type Point = { x: number; y: number }
 type Stroke = { color: string; width: number; points: Point[] }
+type Callout = Point & { id: string; text: string; width: number; height: number; rotation: number; manuallySized: boolean }
+type Tool = 'pen' | 'comment'
+type ResizeEdges = { left: boolean; right: boolean; top: boolean; bottom: boolean }
+
+const ROTATE_CURSOR = `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24'%3E%3Cpath d='M18 8a7 7 0 1 0 1 7M18 4v5h-5' fill='none' stroke='white' stroke-width='4' stroke-linecap='round' stroke-linejoin='round'/%3E%3Cpath d='M18 8a7 7 0 1 0 1 7M18 4v5h-5' fill='none' stroke='%23171717' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E") 12 12, crosshair`
+
+function unrotatePoint(value: Point, center: Point, rotation: number): Point {
+  const angle = -rotation * Math.PI / 180
+  const dx = value.x - center.x
+  const dy = value.y - center.y
+  return { x: center.x + dx * Math.cos(angle) - dy * Math.sin(angle), y: center.y + dx * Math.sin(angle) + dy * Math.cos(angle) }
+}
+
+function calloutFontSize(imageHeight: number): number {
+  return Math.max(14, Math.min(24, imageHeight / 36))
+}
+
+function sizeCallout(text: string, imageWidth: number, imageHeight: number): Pick<Callout, 'width' | 'height'> {
+  const fontSize = calloutFontSize(imageHeight)
+  const lineHeight = fontSize * 1.25
+  const maxTextWidth = Math.max(80, Math.min(imageWidth * 0.6, 420 * imageHeight / 600))
+  const lines = text.split('\n')
+  const widths = lines.map(line => Math.max(fontSize * 2, line.length * fontSize * 0.58))
+  const wrappedLines = widths.reduce((total, lineWidth) => total + Math.max(1, Math.ceil(lineWidth / maxTextWidth)), 0)
+  return {
+    width: Math.min(imageWidth, Math.max(112, Math.min(maxTextWidth, Math.max(...widths)) + 70)),
+    height: Math.min(imageHeight, Math.max(44, wrappedLines * lineHeight + 20)),
+  }
+}
+
+function bubblePath(context: CanvasRenderingContext2D, callout: Callout, radius: number): void {
+  const { x, y, width, height } = callout
+  context.beginPath()
+  context.moveTo(x + radius, y)
+  context.lineTo(x + width - radius, y)
+  context.quadraticCurveTo(x + width, y, x + width, y + radius)
+  context.lineTo(x + width, y + height - radius)
+  context.quadraticCurveTo(x + width, y + height, x + width - radius, y + height)
+  context.lineTo(x + radius, y + height)
+  context.quadraticCurveTo(x, y + height, x, y + height - radius)
+  context.lineTo(x, y + radius)
+  context.quadraticCurveTo(x, y, x + radius, y)
+  context.closePath()
+}
+
+function drawCallout(context: CanvasRenderingContext2D, callout: Callout, imageHeight: number): void {
+  const centerX = callout.x + callout.width / 2
+  const centerY = callout.y + callout.height / 2
+  context.save()
+  context.translate(centerX, centerY)
+  context.rotate(callout.rotation * Math.PI / 180)
+  context.translate(-centerX, -centerY)
+  bubblePath(context, callout, Math.min(18, callout.height / 5))
+  context.fillStyle = 'rgba(18,18,18,0.32)'
+  context.fill()
+  context.strokeStyle = 'rgba(255,255,255,0.32)'
+  context.lineWidth = Math.max(1, imageHeight / 900)
+  context.stroke()
+  const fontSize = calloutFontSize(imageHeight)
+  const lineHeight = fontSize * 1.25
+  context.fillStyle = '#ffffff'
+  context.font = `600 ${fontSize}px system-ui, sans-serif`
+  context.textBaseline = 'top'
+  const maxWidth = callout.width - 28
+  const lines: string[] = []
+  for (const paragraph of callout.text.trim().split('\n')) {
+    const paragraphLines: string[] = []
+    for (const word of paragraph.split(/\s+/)) {
+      const candidate = paragraphLines.length ? `${paragraphLines[paragraphLines.length - 1]} ${word}` : word
+      if (paragraphLines.length && context.measureText(candidate).width > maxWidth) paragraphLines.push(word)
+      else if (paragraphLines.length) paragraphLines[paragraphLines.length - 1] = candidate
+      else paragraphLines.push(candidate)
+    }
+    lines.push(...(paragraphLines.length ? paragraphLines : ['']))
+  }
+  lines.slice(0, Math.max(1, Math.floor((callout.height - 24) / lineHeight))).forEach((line, index) => {
+    context.fillText(line, callout.x + 14, callout.y + 12 + index * lineHeight, maxWidth)
+  })
+  context.restore()
+}
 
 export function ScreenshotDrawing({ id, url, width, height, toolbarHost, onClose, onSaved }: {
   id: string; url: string; width: number; height: number; toolbarHost: HTMLElement | null; onClose: () => void; onSaved: (screenshot: RecentScreenshot, url: string) => void
 }) {
   const [strokes, setStrokes] = useState<Stroke[]>([])
+  const [callouts, setCallouts] = useState<Callout[]>([])
+  const [tool, setTool] = useState<Tool>('pen')
   const [color, setColor] = useState('#ff453a')
   const [brush, setBrush] = useState(4)
   const [saving, setSaving] = useState(false)
   const [message, setMessage] = useState('')
   const activePointer = useRef<number | null>(null)
-  const point = (event: PointerEvent<SVGSVGElement>): Point => {
-    const bounds = event.currentTarget.getBoundingClientRect()
+  const calloutDrag = useRef<{ id: string; pointerId: number; point: Point; x: number; y: number } | null>(null)
+  const calloutResize = useRef<{ id: string; pointerId: number; point: Point; x: number; y: number; width: number; height: number; rotation: number; edges: ResizeEdges } | null>(null)
+  const calloutRotation = useRef<{ id: string; pointerId: number; center: Point; angle: number; rotation: number } | null>(null)
+  const svgRef = useRef<SVGSVGElement>(null)
+  const point = (event: { clientX: number; clientY: number }): Point => {
+    const bounds = svgRef.current?.getBoundingClientRect()
+    if (!bounds) return { x: 0, y: 0 }
     return {
       x: Math.max(0, Math.min(width, (event.clientX - bounds.left) * width / bounds.width)),
       y: Math.max(0, Math.min(height, (event.clientY - bounds.top) * height / bounds.height)),
@@ -45,6 +132,9 @@ export function ScreenshotDrawing({ id, url, width, height, toolbarHost, onClose
         for (const p of stroke.points.slice(1)) context.lineTo(p.x, p.y)
         context.stroke()
       }
+      for (const callout of callouts) {
+        if (callout.text.trim()) drawCallout(context, callout, height)
+      }
       const dataUrl = canvas.toDataURL('image/png')
       if (typeof window.electronAPI.saveRecentScreenshot !== 'function') {
         setMessage('Restart Cate to enable saving to the screenshot stack. Your drawing is still here.')
@@ -61,11 +151,21 @@ export function ScreenshotDrawing({ id, url, width, height, toolbarHost, onClose
   }
   const buttonClass = 'flex h-8 shrink-0 items-center justify-center gap-1.5 rounded-full px-3 text-xs font-medium text-white/80 transition-colors hover:bg-white/10 hover:text-white disabled:opacity-30 focus-visible:outline focus-visible:outline-2 focus-visible:outline-white'
   return <>
-    <svg viewBox={`0 0 ${width} ${height}`} aria-label="Draw on screenshot"
+    <svg ref={svgRef} viewBox={`0 0 ${width} ${height}`} aria-label="Annotate screenshot"
       className="absolute inset-0 h-full w-full touch-none cursor-crosshair rounded-xl"
-      onClick={event => event.stopPropagation()}
+      onClick={event => {
+        event.stopPropagation()
+        if (tool !== 'comment' || saving) return
+        const p = point(event)
+        const { width: bubbleWidth, height: bubbleHeight } = sizeCallout('', width, height)
+        setCallouts(current => [...current, {
+          id: crypto.randomUUID(), text: '', width: bubbleWidth, height: bubbleHeight, rotation: 0, manuallySized: false,
+          x: Math.max(0, Math.min(width - bubbleWidth, p.x - bubbleWidth / 2)),
+          y: Math.max(0, Math.min(height - bubbleHeight, p.y - bubbleHeight / 2)),
+        }])
+      }}
       onPointerDown={event => {
-        if (event.button !== 0 || saving || activePointer.current !== null) return
+        if (tool !== 'pen' || event.button !== 0 || saving || activePointer.current !== null) return
         event.preventDefault()
         event.stopPropagation()
         event.currentTarget.setPointerCapture(event.pointerId)
@@ -82,12 +182,111 @@ export function ScreenshotDrawing({ id, url, width, height, toolbarHost, onClose
       onPointerUp={event => { if (activePointer.current === event.pointerId) activePointer.current = null }}
       onPointerCancel={() => { activePointer.current = null }}
       onLostPointerCapture={() => { activePointer.current = null }}>
+      <rect width={width} height={height} fill="transparent" pointerEvents="all" />
       {strokes.map((stroke, index) => <polyline key={index} points={stroke.points.map(p => `${p.x},${p.y}`).join(' ')}
         fill="none" stroke={stroke.color} strokeWidth={stroke.width} strokeLinecap="round" strokeLinejoin="round" />)}
+      {callouts.map((callout, index) => {
+        const center = { x: callout.x + callout.width / 2, y: callout.y + callout.height / 2 }
+        return <g key={callout.id} transform={`rotate(${callout.rotation} ${center.x} ${center.y})`}>
+          <foreignObject x={callout.x} y={callout.y} width={callout.width} height={callout.height}
+            onClick={event => event.stopPropagation()}>
+          <div className="group relative h-full w-full overflow-hidden rounded-2xl bg-black/30 text-white shadow-xl backdrop-blur-sm" xmlns="http://www.w3.org/1999/xhtml">
+            <button type="button" aria-label={`Move comment ${index + 1}`} title="Drag comment"
+              className="absolute left-1.5 top-1/2 z-10 -translate-y-1/2 cursor-grab rounded-full p-1 text-white/65 hover:bg-white/15 hover:text-white active:cursor-grabbing"
+              onClick={event => event.stopPropagation()}
+              onPointerDown={event => {
+                event.preventDefault(); event.stopPropagation(); event.currentTarget.setPointerCapture(event.pointerId)
+                calloutDrag.current = { id: callout.id, pointerId: event.pointerId, point: point(event), x: callout.x, y: callout.y }
+              }}
+              onPointerMove={event => {
+                const drag = calloutDrag.current
+                if (!drag || drag.id !== callout.id || drag.pointerId !== event.pointerId) return
+                const current = point(event)
+                setCallouts(values => values.map(value => value.id === callout.id ? {
+                  ...value,
+                  x: Math.max(0, Math.min(width - value.width, drag.x + current.x - drag.point.x)),
+                  y: Math.max(0, Math.min(height - value.height, drag.y + current.y - drag.point.y)),
+                } : value))
+              }}
+              onPointerUp={event => { if (calloutDrag.current?.pointerId === event.pointerId) calloutDrag.current = null }}
+              onPointerCancel={() => { calloutDrag.current = null }}><DotsSix size={15} weight="bold" /></button>
+            <button type="button" aria-label={`Delete comment ${index + 1}`} className="absolute right-1.5 top-1/2 z-10 -translate-y-1/2 rounded-full p-1 text-white/65 opacity-0 transition-opacity hover:bg-white/15 hover:text-white group-hover:opacity-100 group-focus-within:opacity-100"
+              onPointerDown={event => event.stopPropagation()} onClick={() => setCallouts(current => current.filter(value => value.id !== callout.id))}><Trash size={12} /></button>
+            <textarea autoFocus={index === callouts.length - 1} aria-label={`Comment ${index + 1}`} placeholder="Add a comment…" value={callout.text}
+              onPointerDown={event => event.stopPropagation()} onClick={event => event.stopPropagation()}
+              onChange={event => {
+                const text = event.target.value
+                setCallouts(current => current.map(value => value.id === callout.id ? {
+                  ...value, ...(value.manuallySized ? {} : sizeCallout(text, width, height)), text,
+                } : value))
+              }}
+              className="h-full w-full resize-none overflow-auto bg-transparent py-2.5 pl-9 pr-8 font-semibold leading-tight text-white outline-none placeholder:text-white/55"
+              style={{ fontSize: calloutFontSize(height) }} />
+          </div>
+          </foreignObject>
+          <g aria-label={`Resize comment ${index + 1}`} className="cursor-nwse-resize"
+            onClick={event => event.stopPropagation()}
+            onPointerDown={event => {
+              event.preventDefault(); event.stopPropagation(); event.currentTarget.setPointerCapture(event.pointerId)
+              const current = point(event)
+              const local = unrotatePoint(current, center, callout.rotation)
+              const horizontal = Math.abs(local.x - callout.x) < Math.abs(local.x - callout.x - callout.width) ? 'left' : 'right'
+              const vertical = Math.abs(local.y - callout.y) < Math.abs(local.y - callout.y - callout.height) ? 'top' : 'bottom'
+              const nearHorizontal = Math.min(Math.abs(local.x - callout.x), Math.abs(local.x - callout.x - callout.width)) <= 14
+              const nearVertical = Math.min(Math.abs(local.y - callout.y), Math.abs(local.y - callout.y - callout.height)) <= 14
+              calloutResize.current = {
+                id: callout.id, pointerId: event.pointerId, point: current, x: callout.x, y: callout.y, width: callout.width, height: callout.height, rotation: callout.rotation,
+                edges: { left: nearHorizontal && horizontal === 'left', right: nearHorizontal && horizontal === 'right', top: nearVertical && vertical === 'top', bottom: nearVertical && vertical === 'bottom' },
+              }
+            }}
+            onPointerMove={event => {
+              const drag = calloutResize.current
+              if (!drag || drag.id !== callout.id || drag.pointerId !== event.pointerId) return
+              const localStart = unrotatePoint(drag.point, center, drag.rotation)
+              const localCurrent = unrotatePoint(point(event), center, drag.rotation)
+              const dx = localCurrent.x - localStart.x
+              const dy = localCurrent.y - localStart.y
+              let x = drag.x; let y = drag.y; let nextWidth = drag.width; let nextHeight = drag.height
+              if (drag.edges.right) nextWidth = Math.max(80, Math.min(width - x, drag.width + dx))
+              if (drag.edges.bottom) nextHeight = Math.max(44, Math.min(height - y, drag.height + dy))
+              if (drag.edges.left) { x = Math.max(0, Math.min(drag.x + drag.width - 80, drag.x + dx)); nextWidth = drag.width + drag.x - x }
+              if (drag.edges.top) { y = Math.max(0, Math.min(drag.y + drag.height - 44, drag.y + dy)); nextHeight = drag.height + drag.y - y }
+              setCallouts(values => values.map(value => value.id === callout.id ? { ...value, x, y, width: nextWidth, height: nextHeight, manuallySized: true } : value))
+            }}
+            onPointerUp={event => { if (calloutResize.current?.pointerId === event.pointerId) calloutResize.current = null }}
+            onPointerCancel={() => { calloutResize.current = null }}>
+            <rect x={callout.x} y={callout.y} width={callout.width} height={callout.height}
+              fill="none" stroke="transparent" strokeWidth="16" pointerEvents="stroke" />
+          </g>
+          <g aria-label={`Rotate comment ${index + 1}`} style={{ cursor: ROTATE_CURSOR }}
+            onClick={event => event.stopPropagation()}
+            onPointerDown={event => {
+              event.preventDefault(); event.stopPropagation(); event.currentTarget.setPointerCapture(event.pointerId)
+              const current = point(event)
+              calloutRotation.current = { id: callout.id, pointerId: event.pointerId, center, angle: Math.atan2(current.y - center.y, current.x - center.x), rotation: callout.rotation }
+            }}
+            onPointerMove={event => {
+              const drag = calloutRotation.current
+              if (!drag || drag.id !== callout.id || drag.pointerId !== event.pointerId) return
+              const current = point(event)
+              const angle = Math.atan2(current.y - drag.center.y, current.x - drag.center.x)
+              setCallouts(values => values.map(value => value.id === callout.id ? { ...value, rotation: drag.rotation + (angle - drag.angle) * 180 / Math.PI } : value))
+            }}
+            onPointerUp={event => { if (calloutRotation.current?.pointerId === event.pointerId) calloutRotation.current = null }}
+            onPointerCancel={() => { calloutRotation.current = null }}>
+            <rect x={callout.x - 20} y={callout.y - 20} width={callout.width + 40} height={callout.height + 40}
+              rx={20} fill="none" stroke="transparent" strokeWidth="12" pointerEvents="stroke" />
+          </g>
+        </g>
+      })}
     </svg>
     {toolbarHost && createPortal(
     <div role="toolbar" aria-label="Screenshot drawing tools" className="titlebar-no-drag flex max-w-[calc(100vw-160px)] flex-wrap items-center justify-center gap-2 rounded-2xl border border-white/10 bg-neutral-800/90 px-3 py-2 shadow-xl backdrop-blur-md"
       onClick={event => event.stopPropagation()} onPointerDown={event => event.stopPropagation()}>
+      <button type="button" aria-label="Draw with pen" title="Pen" aria-pressed={tool === 'pen'} onClick={() => setTool('pen')}
+        className={`flex h-9 w-9 items-center justify-center rounded-full ${tool === 'pen' ? 'bg-white text-neutral-900' : 'bg-white/10 text-white/70 hover:bg-white/20 hover:text-white'}`}><PencilSimple size={17} /></button>
+      <button type="button" aria-label="Add comment" title="Comment" aria-pressed={tool === 'comment'} onClick={() => setTool('comment')}
+        className={`flex h-9 w-9 items-center justify-center rounded-full ${tool === 'comment' ? 'bg-white text-neutral-900' : 'bg-white/10 text-white/70 hover:bg-white/20 hover:text-white'}`}><ChatCircleText size={17} /></button>
       <div className="flex items-center gap-2" aria-label="Pen colors">
         {['#ff453a', '#ffcc00', '#30d158', '#0a84ff', '#ffffff'].map(value => <button key={value} type="button"
           aria-label={`Pen color ${value}`} aria-pressed={color === value} onClick={() => setColor(value)}
@@ -105,7 +304,7 @@ export function ScreenshotDrawing({ id, url, width, height, toolbarHost, onClose
       <span className="h-5 w-px bg-white/10" />
       <button type="button" className={buttonClass} disabled={saving} onClick={onClose}>Cancel</button>
       <button type="button" className="flex h-8 items-center gap-1.5 rounded-full bg-white px-3 text-xs font-semibold text-neutral-900 transition-colors hover:bg-white/90 disabled:opacity-35"
-        disabled={!strokes.length || saving} onClick={() => { void save() }}><DownloadSimple size={15} />{saving ? 'Saving...' : 'Save'}</button>
+        disabled={(!strokes.length && !callouts.some(callout => callout.text.trim())) || saving} onClick={() => { void save() }}><DownloadSimple size={15} />{saving ? 'Saving...' : 'Save'}</button>
       {message && <span role="status" className="absolute left-1/2 top-full mt-2 w-max max-w-[80vw] -translate-x-1/2 rounded-lg bg-neutral-800 px-3 py-2 text-sm text-white">{message}</span>}
     </div>, toolbarHost)}
   </>
diff --git a/src/renderer/canvas/useCanvasNodeStyle.ts b/src/renderer/canvas/useCanvasNodeStyle.ts
index 944121c3..ea56ee7c 100644
--- a/src/renderer/canvas/useCanvasNodeStyle.ts
+++ b/src/renderer/canvas/useCanvasNodeStyle.ts
@@ -6,7 +6,6 @@
 // =============================================================================
 
 import React, { useMemo } from 'react'
-import { isMaximized } from '../../shared/types'
 import type { CanvasNodeState, NodeActivityState } from '../../shared/types'
 import { NODE_CORNER_RADIUS as CORNER_RADIUS } from './nodeAppearance'
 
@@ -83,7 +82,7 @@ export function useCanvasNodeStyle(args: StyleArgs) {
       'border-color 150ms ease, box-shadow 200ms ease, outline-color 200ms ease, transform 200ms cubic-bezier(0.34, 1.56, 0.64, 1), opacity 150ms ease-out, filter 200ms ease'
 
 
-    const baseOpacity = isEntering ? 0 : isExiting ? 0 : isWholeNodeDragSource ? 0 : 1
+    const baseOpacity = isEntering ? 0 : isExiting ? 0 : 1
     // Focus lens: nodes outside the focused worktree recede.
     const opacity = worktreeDim ? baseOpacity * 0.5 : baseOpacity
 
@@ -113,24 +112,20 @@ export function useCanvasNodeStyle(args: StyleArgs) {
       filter: worktreeDim ? 'saturate(0.4)' : undefined,
       transform: isEntering ? 'scale(0.85)' : isExiting ? 'scale(0.9)' : 'scale(1)',
       opacity,
+      // Electron webviews are separate guest surfaces and can remain painted
+      // through an opacity:0 ancestor. visibility reliably suppresses the guest
+      // whenever this node must fall back to the generic drag ghost.
+      visibility: isWholeNodeDragSource ? 'hidden' : undefined,
       pointerEvents: isExiting || isWholeNodeDragSource ? 'none' : undefined,
       userSelect: 'none',
-      ...(isMaximized(node) ? {
-        position: 'absolute', left: 0, top: 0, width: '100%', height: '100%',
-        zIndex: 50, borderRadius: 0, border: 'none', boxShadow: 'none',
-        transform: 'none', transition: 'none', filter: 'none',
-        opacity: isExiting || isWholeNodeDragSource ? 0 : 1,
-        ['--node-inner-radius' as any]: '0px',
-      } as React.CSSProperties : {}),
     }
   }, [node, isFocused, isSelected, activityState, isHovered, chromeTint, isWholeNodeDragSource, worktreeDim])
 
   const glowStyle = useMemo<React.CSSProperties | null>(() => {
-    if (!node || isMaximized(node)) return null
+    if (!node) return null
     if (!(isFocused || isSelected || worktreeHighlight)) return null
     // Hide the focus glow while the node is the drag source — the source node
-    // itself is hidden (containerStyle.opacity = 0 above) and the glow would
-    // otherwise float at the node's original origin while the ghost moves.
+    // itself is hidden and the glow would otherwise overlap the ghost.
     if (isWholeNodeDragSource) return null
     const isEntering = node.animationState === 'entering'
     const isExiting = node.animationState === 'exiting'
diff --git a/src/renderer/docking/DockLayoutRenderer.tsx b/src/renderer/docking/DockLayoutRenderer.tsx
index f87f328c..42ab5fb7 100644
--- a/src/renderer/docking/DockLayoutRenderer.tsx
+++ b/src/renderer/docking/DockLayoutRenderer.tsx
@@ -1,7 +1,5 @@
 import React from 'react'
 import type { DockLayoutNode, DockTabStack as DockTabStackNode, PanelType } from '../../shared/types'
-import { useDockStoreContext } from '../stores/DockStoreContext'
-import { findTabStack } from '../stores/dockTreeUtils'
 import { layoutMinimum } from './splitSizing'
 import DockSplitContainer from './DockSplitContainer'
 
@@ -13,9 +11,7 @@ interface DockLayoutRendererProps {
 
 /** Shared recursive renderer for window docks and canvas-node mini-docks. */
 export default function DockLayoutRenderer({ layout, renderTabs, getPanelType }: DockLayoutRendererProps) {
-  const maximizedId = useDockStoreContext((s) => s.maximizedStackId)
-  const maximized = maximizedId ? findTabStack(layout, maximizedId) : null
-  const minimum = layoutMinimum(maximized ?? layout, getPanelType)
+  const minimum = layoutMinimum(layout, getPanelType)
   const renderNode = (node: DockLayoutNode, isRoot: boolean): React.ReactNode => {
     if (node.type === 'tabs') return renderTabs(node, isRoot)
     return (
diff --git a/src/renderer/docking/DockSplitContainer.tsx b/src/renderer/docking/DockSplitContainer.tsx
index db6524ca..f088e01d 100644
--- a/src/renderer/docking/DockSplitContainer.tsx
+++ b/src/renderer/docking/DockSplitContainer.tsx
@@ -6,7 +6,6 @@
 import React, { useCallback, useRef } from 'react'
 import { useDockStoreContext } from '../stores/DockStoreContext'
 import { type DockLayoutNode, type DockSplitNode, type PanelType } from '../../shared/types'
-import { findTabStack } from '../stores/dockTreeUtils'
 import { layoutMinimum, SPLIT_DIVIDER_SIZE } from './splitSizing'
 import DockResizeHandle from './DockResizeHandle'
 
@@ -42,8 +41,6 @@ export default function DockSplitContainer({
   getPanelType,
 }: DockSplitContainerProps) {
   const setSplitRatio = useDockStoreContext((s) => s.setSplitRatio)
-  const maximizedStackId = useDockStoreContext((s) => s.maximizedStackId)
-  const containsMaximized = !!maximizedStackId && !!findTabStack(node, maximizedStackId)
   const isHorizontal = node.direction === 'horizontal'
   const containerRef = useRef<HTMLDivElement>(null)
 
@@ -98,16 +95,15 @@ export default function DockSplitContainer({
           <div
             data-dock-pane={child.id}
             style={{
-              [isHorizontal ? 'width' : 'height']: containsMaximized ? '100%' : `calc((100% - ${SPLIT_DIVIDER_SIZE * (node.children.length - 1)}px) * ${node.ratios[i]})`,
-              display: containsMaximized && !findTabStack(child, maximizedStackId!) ? 'none' : undefined,
-              minWidth: containsMaximized ? 0 : minimum.width,
-              minHeight: containsMaximized ? 0 : minimum.height,
+              [isHorizontal ? 'width' : 'height']: `calc((100% - ${SPLIT_DIVIDER_SIZE * (node.children.length - 1)}px) * ${node.ratios[i]})`,
+              minWidth: minimum.width,
+              minHeight: minimum.height,
             }}
             className="shrink overflow-hidden"
           >
             {renderNode(child)}
           </div>
-          {!containsMaximized && i < node.children.length - 1 && (
+          {i < node.children.length - 1 && (
             <DockResizeHandle
               direction={isHorizontal ? 'horizontal' : 'vertical'}
               onResize={(delta) => handleResize(i, delta)}
diff --git a/src/renderer/docking/DockSplitMaximize.test.tsx b/src/renderer/docking/DockSplitMaximize.test.tsx
deleted file mode 100644
index 3ce564da..00000000
--- a/src/renderer/docking/DockSplitMaximize.test.tsx
+++ /dev/null
@@ -1,47 +0,0 @@
-import React, { act, useEffect } from 'react'
-import { createRoot } from 'react-dom/client'
-import { expect, it, vi } from 'vitest'
-import { createDockStore } from '../stores/dockStore'
-import { DockStoreProvider } from '../stores/DockStoreContext'
-import DockLayoutRenderer from './DockLayoutRenderer'
-import type { DockLayoutNode } from '../../shared/types'
-
-it('maximizes nested panes without remounting or changing ratios and restores the layout', () => {
-  const tabs = (id: string): DockLayoutNode => ({ id, type: 'tabs', panelIds: [id], activeIndex: 0 })
-  const layout: DockLayoutNode = { id: 'outer', type: 'split', direction: 'horizontal', ratios: [0.3, 0.7], children: [tabs('a'), {
-    id: 'inner', type: 'split', direction: 'vertical', ratios: [0.4, 0.6], children: [tabs('b'), tabs('c')],
-  }] }
-  const store = createDockStore()
-  const mounted = vi.fn()
-  const unmounted = vi.fn()
-  function Panel({ id }: { id: string }) {
-    useEffect(() => { mounted(id); return () => unmounted(id) }, [id])
-    return <div data-panel={id} />
-  }
-  const host = document.createElement('div')
-  const root = createRoot(host)
-  try {
-    act(() => root.render(<DockStoreProvider store={store}><DockLayoutRenderer layout={layout} renderTabs={(stack) => <Panel id={stack.id} />} /></DockStoreProvider>))
-    const a = host.querySelector('[data-panel="a"]')!.parentElement!
-    const b = host.querySelector('[data-panel="b"]')!.parentElement!
-    const c = host.querySelector('[data-panel="c"]')!.parentElement!
-    act(() => store.getState().toggleStackMaximized('c'))
-    expect(a.style.display).toBe('none')
-    expect(b.style.display).toBe('none')
-    expect(c.style.height).toBe('100%')
-    expect(host.querySelector('.cursor-col-resize')).toBeNull()
-    expect(mounted).toHaveBeenCalledTimes(3)
-    expect(unmounted).not.toHaveBeenCalled()
-    act(() => store.getState().toggleStackMaximized('c'))
-    expect(a.style.display).toBe('')
-    expect(a.style.width).toContain('0.3')
-    expect(b.style.height).toContain('0.4')
-    expect(c.style.height).toContain('0.6')
-    expect(mounted).toHaveBeenCalledTimes(3)
-    act(() => store.getState().toggleStackMaximized('missing'))
-    expect(a.style.display).toBe('')
-    expect(b.style.display).toBe('')
-    store.getState().restoreSnapshot(store.getState().getSnapshot())
-    expect(store.getState().maximizedStackId).toBeNull()
-  } finally { act(() => root.unmount()) }
-})
diff --git a/src/renderer/docking/DockTabStack.tsx b/src/renderer/docking/DockTabStack.tsx
index 1e263985..20f224bc 100644
--- a/src/renderer/docking/DockTabStack.tsx
+++ b/src/renderer/docking/DockTabStack.tsx
@@ -52,16 +52,30 @@ interface DockTabStackProps {
   /** When true, this stack's drop-zone returns a null rect so it can't be
    *  hit-tested as a target. */
   dropDisabled?: boolean
+  /** Canvas-node stacks promote their active panel into the canvas's owning
+   *  dock instead of merging their private mini-dock. */
+  onPresentPanel?: (panelId: string) => void
 }
 
-export default function DockTabStack({ stack, zone: zoneProp, renderPanel, getPanelTitle, onClosePanel, onClosePanels, getPanel: getPanelProp, workspaceId: workspaceIdProp, onPanelRemoved, onPanelRenamed, excludePanelTypes, trailingControls, newTabControl, onTabBarMouseDown, localOnly, compact, dropDisabled }: DockTabStackProps) {
+export default function DockTabStack({ stack, zone: zoneProp, renderPanel, getPanelTitle, onClosePanel, onClosePanels, getPanel: getPanelProp, workspaceId: workspaceIdProp, onPanelRemoved, onPanelRenamed, excludePanelTypes, trailingControls, newTabControl, onTabBarMouseDown, localOnly, compact, dropDisabled, onPresentPanel }: DockTabStackProps) {
   const dockStoreApi = useDockStoreApi()
-  const canMaximize = useDockStoreContext((s) => Object.values(s.zones).some((zone) =>
-    zone.visible && zone.layout && (zone.layout.type === 'split' || zone.layout.id !== stack.id),
-  ))
-  const maximized = useDockStoreContext((s) => s.maximizedStackId === stack.id)
+  const presentation = useDockStoreContext((s) => s.presentation)
+  const zoneLayout = useDockStoreContext((s) => s.zones[zoneProp].layout)
+  const activePanelId = stack.panelIds[stack.activeIndex]
+  const ownsPresentation = presentation?.stackId === stack.id
+  const canRestore = !!ownsPresentation && dockStoreApi.getState().canRestorePresentation(stack.id)
+  const presented = ownsPresentation
+    && (!presentation.panelId || presentation.panelId === activePanelId)
+  const canMerge = !presentation && zoneLayout?.type === 'split'
   const stackRef = useRef<HTMLDivElement>(null)
 
+  // A structural mutation makes the saved reverse operation unsafe. Drop the
+  // transaction immediately so it cannot leave dead controls or block a later
+  // presentation; the already-mutated real dock tree remains authoritative.
+  useEffect(() => {
+    if (ownsPresentation && !canRestore) dockStoreApi.getState().discardPresentation()
+  }, [ownsPresentation, canRestore, dockStoreApi])
+
   const isDragging = useDragStore((s) => s.isDragging)
   const target = useDragStore((s) => s.target)
   const dragSource = useDragStore((s) => s.source)
@@ -86,8 +100,6 @@ export default function DockTabStack({ stack, zone: zoneProp, renderPanel, getPa
     })
   }, [stack.id, zoneProp, dockStoreApi, acceptsPanelType])
 
-  const activePanelId = stack.panelIds[stack.activeIndex]
-
   // Effective workspace for status lookups: explicit prop, else the selected
   // workspace (matches resolvePanel's fallback). Subscribed so a workspace
   // switch re-scopes the tab agent indicators.
@@ -115,7 +127,7 @@ export default function DockTabStack({ stack, zone: zoneProp, renderPanel, getPa
     const viewport = element.closest<HTMLElement>('[data-dock-viewport]')
     const dock = dockStoreApi.getState()
     const layout = dock.zones[zoneProp].layout
-    if (viewport && layout && !dock.maximizedStackId) {
+    if (viewport && layout) {
       return canSplitLayout(layout, stack.id, viewport.clientWidth, viewport.clientHeight, (id) => resolvePanel(id)?.type)
     }
     return canSplitPane(Math.min(element.clientWidth, viewport?.clientWidth ?? element.clientWidth),
@@ -325,16 +337,24 @@ export default function DockTabStack({ stack, zone: zoneProp, renderPanel, getPa
           </Tooltip>
         )}
 
-        {canMaximize && <Tooltip label={maximized ? 'Restore split' : 'Maximize split'}>
+        {(presented || canMerge || !!onPresentPanel) && <Tooltip label={
+          presented
+            ? canRestore ? 'Restore previous layout' : 'Previous layout can no longer be restored'
+            : onPresentPanel ? 'Move panel into dock' : 'Merge splits into tabs'
+        }>
           <button
             type="button"
-            aria-label={maximized ? 'Restore split' : 'Maximize split'}
-            aria-pressed={maximized}
+            aria-label={presented ? 'Restore previous layout' : onPresentPanel ? 'Move panel into dock' : 'Merge splits into tabs'}
+            aria-pressed={presented}
             className={`flex items-center justify-center self-center rounded-[10px] text-muted hover:text-primary hover:bg-hover cursor-pointer ${compact ? 'w-[22px] h-[22px]' : 'w-6 h-6'}`}
             onMouseDown={(event) => event.stopPropagation()}
-            onClick={() => dockStoreApi.getState().toggleStackMaximized(stack.id)}
+            onClick={() => {
+              if (presented) dockStoreApi.getState().restorePresentation(stack.id)
+              else if (onPresentPanel && activePanelId) onPresentPanel(activePanelId)
+              else dockStoreApi.getState().mergeSplitToStack(stack.id)
+            }}
           >
-            {maximized ? <Minimize2 size={compact ? 12 : 14} /> : <Maximize2 size={compact ? 12 : 14} />}
+            {presented ? <Minimize2 size={compact ? 12 : 14} /> : <Maximize2 size={compact ? 12 : 14} />}
           </button>
         </Tooltip>}
 
diff --git a/src/renderer/docking/SurfacePanels.test.tsx b/src/renderer/docking/SurfacePanels.test.tsx
index cb6d6501..034635e3 100644
--- a/src/renderer/docking/SurfacePanels.test.tsx
+++ b/src/renderer/docking/SurfacePanels.test.tsx
@@ -178,31 +178,51 @@ it('refreshes canvas chrome when panel records settle without a layout change',
   expect(host.querySelector('.dock-tab-bar')?.classList.contains('border-b')).toBe(false)
 })
 
-it('offers maximize and restore in each split header', () => {
+it('merges splits into tabs and restores the previous layout', () => {
   act(() => root.render(<FullDock />))
-  expect(host.querySelector('[aria-label="Maximize split"]')).toBeNull()
+  expect(host.querySelector('[aria-label="Merge splits into tabs"]')).toBeNull()
   act(() => (host.querySelector('[aria-label="Split Right"]') as HTMLButtonElement).click())
-  const buttons = host.querySelectorAll<HTMLButtonElement>('[aria-label="Maximize split"]')
+  const buttons = host.querySelectorAll<HTMLButtonElement>('[aria-label="Merge splits into tabs"]')
   expect(buttons).toHaveLength(2)
   const layout = dock.getState().zones.center.layout
   act(() => buttons[1].click())
-  const restore = host.querySelector<HTMLButtonElement>('[aria-label="Restore split"]')!
+  const restore = host.querySelector<HTMLButtonElement>('[aria-label="Restore previous layout"]')!
   expect(restore.getAttribute('aria-pressed')).toBe('true')
-  expect(dock.getState().zones.center.layout).toBe(layout)
+  expect(dock.getState().zones.center.layout?.type).toBe('tabs')
   act(() => restore.click())
-  expect(dock.getState().maximizedStackId).toBeNull()
-  expect(host.querySelectorAll('[aria-label="Maximize split"]')).toHaveLength(2)
+  expect(dock.getState().zones.center.layout).toBe(layout)
+  expect(host.querySelectorAll('[aria-label="Merge splits into tabs"]')).toHaveLength(2)
 })
 
+it('shows canvas-promotion restore only while the promoted panel is active', () => {
+  const restoreLayout = dock.getState().zones.center.layout!
+  useAppStore.getState().addPanel('test', { id: 'promoted', type: 'editor', title: 'Promoted', isDirty: false })
+  dock.getState().dockPanel('promoted', 'center', { type: 'tab', stackId })
+  const expectedLayout = dock.getState().zones.center.layout!
+  dock.getState().beginPresentation({
+    stackId,
+    panelId: 'promoted',
+    zone: 'center',
+    restoreLayout,
+    expectedLayout,
+  })
+  act(() => root.render(<FullDock />))
+  expect(host.querySelector('[aria-label="Restore previous layout"]')).not.toBeNull()
+
+  act(() => dock.getState().setActiveTab(stackId, 0))
+  expect(host.querySelector('[aria-label="Restore previous layout"]')).toBeNull()
+
+  act(() => dock.getState().setActiveTab(stackId, 1))
+  expect(host.querySelector('[aria-label="Restore previous layout"]')).not.toBeNull()
+})
 
-it('splitting a maximized pane reveals the new pane', () => {
+it('discards restore after changing the merged layout', () => {
   act(() => root.render(<FullDock />))
   act(() => (host.querySelector('[aria-label="Split Right"]') as HTMLButtonElement).click())
-  act(() => (host.querySelector('[aria-label="Maximize split"]') as HTMLButtonElement).click())
-  expect(dock.getState().maximizedStackId).not.toBeNull()
+  act(() => (host.querySelector('[aria-label="Merge splits into tabs"]') as HTMLButtonElement).click())
   act(() => (host.querySelector('[aria-label="Split Right"]') as HTMLButtonElement).click())
-  expect(dock.getState().maximizedStackId).toBeNull()
-  expect(host.querySelectorAll('[aria-label="Maximize split"]')).toHaveLength(3)
+  expect(dock.getState().presentation).toBeNull()
+  expect(host.querySelector('[aria-label="Restore previous layout"]')).toBeNull()
 })
 
 
diff --git a/src/renderer/drag/__tests__/harness.tsx b/src/renderer/drag/__tests__/harness.tsx
index f6a62ad7..d0a25daf 100644
--- a/src/renderer/drag/__tests__/harness.tsx
+++ b/src/renderer/drag/__tests__/harness.tsx
@@ -48,8 +48,6 @@ export interface NodeSpec {
   panelType?: PanelType
   origin: Point
   size: Size
-  preMaximizeOrigin?: Point
-  preMaximizeSize?: Size
 }
 
 export interface SceneSpec {
@@ -182,9 +180,6 @@ function TestNode({ spec, canvasStore }: { spec: NodeSpec; canvasStore: StoreApi
         id: finalId,
         origin: spec.origin,
         size: spec.size,
-        ...(spec.preMaximizeOrigin && spec.preMaximizeSize
-          ? { preMaximizeOrigin: spec.preMaximizeOrigin, preMaximizeSize: spec.preMaximizeSize }
-          : {}),
       }
       return { ...s, nodes: next }
     })
diff --git a/src/renderer/drag/__tests__/scenarios.test.tsx b/src/renderer/drag/__tests__/scenarios.test.tsx
index 05bf4d5f..347012ff 100644
--- a/src/renderer/drag/__tests__/scenarios.test.tsx
+++ b/src/renderer/drag/__tests__/scenarios.test.tsx
@@ -5,8 +5,8 @@
 //
 // Numbered scenarios match Phase 1 of the plan. Dock-related scenarios (6, 7,
 // 10) require dock-stack support in the harness and are skipped pending a
-// follow-up harness extension. preMaximizeSize / proportional grab / cross-
-// store invariant are the high-priority regressions targeted here.
+// follow-up harness extension. Cross-store invariants are the high-priority
+// regressions targeted here.
 // =============================================================================
 
 import { describe, it, expect, vi, afterEach } from 'vitest'
@@ -167,57 +167,6 @@ describe('drag integration — canvas-node scenarios', () => {
     expect(store.getState().nodes['n1'].origin).toEqual(initialOrigin)
   })
 
-  // ---------------------------------------------------------------------------
-  // 4. preMaximizeSize ghost sizing — drag a maximized node; ghost size =
-  //    preMaximizeSize, not the current (maximized) size. Lost in 0.4.4.
-  // ---------------------------------------------------------------------------
-  it('4: ghost size for a maximized node equals preMaximizeSize', () => {
-    scene = renderDragScene({
-      canvases: [{ panelId: 'c1', rect: { x: 0, y: 0, w: 1000, h: 800 } }],
-      nodes: [{
-        canvasPanelId: 'c1',
-        nodeId: 'n1',
-        origin: { x: 0, y: 0 },
-        size: { width: 1000, height: 800 }, // maximized
-        preMaximizeOrigin: { x: 200, y: 150 },
-        preMaximizeSize: { width: 300, height: 200 },
-      }],
-    })
-    scene.mouse.downOnNode('n1', { offset: { x: 500, y: 400 } })
-    scene.mouse.moveBy({ x: 50, y: 50 })
-    const drag = scene.drag()
-    expect(drag.isDragging).toBe(true)
-    expect(drag.ghostSize?.width).toBe(300)
-    expect(drag.ghostSize?.height).toBe(200)
-    scene.mouse.up()
-  })
-
-  // ---------------------------------------------------------------------------
-  // 5. Proportional grab on maximized node — cursor lands at same relative
-  //    fraction inside the smaller ghost.
-  // ---------------------------------------------------------------------------
-  it('5: grab on a maximized node is projected proportionally into the pre-maximize rect', () => {
-    scene = renderDragScene({
-      canvases: [{ panelId: 'c1', rect: { x: 0, y: 0, w: 1000, h: 800 } }],
-      nodes: [{
-        canvasPanelId: 'c1',
-        nodeId: 'n1',
-        origin: { x: 0, y: 0 },
-        size: { width: 1000, height: 800 },
-        preMaximizeOrigin: { x: 0, y: 0 },
-        preMaximizeSize: { width: 300, height: 200 },
-      }],
-    })
-    // Grab at (750, 600): fraction (0.75, 0.75) of the maximized footprint.
-    scene.mouse.downOnNode('n1', { offset: { x: 750, y: 600 } })
-    scene.mouse.moveBy({ x: 10, y: 10 })
-    const drag = scene.drag()
-    expect(drag.isDragging).toBe(true)
-    // Expected grab = 0.75 × ghostSize.
-    expect(drag.grab?.x).toBeCloseTo(0.75 * 300, 0)
-    expect(drag.grab?.y).toBeCloseTo(0.75 * 200, 0)
-  })
-
   // ---------------------------------------------------------------------------
   // 8. Cross-store invariant — drop from canvas A onto canvas B: the resolved
   //    target's canvasStoreApi must match canvas B's store, not A's. The
diff --git a/src/renderer/drag/useDragOp.ts b/src/renderer/drag/useDragOp.ts
index 71cd6a87..8332d1d1 100644
--- a/src/renderer/drag/useDragOp.ts
+++ b/src/renderer/drag/useDragOp.ts
@@ -159,21 +159,8 @@ function measureCanvasNodeGrab(
       ghostZoom: zoom,
     }
   }
-  // If the node is currently maximized, the spring-load effect (see
-  // CanvasNode's drag-store subscription) will un-maximize it ~200ms into
-  // the drag, snapping node.size/origin back to preMaximizeSize/Origin. The
-  // ghost is sized once at START and isn't re-measured, so taking the live
-  // maximized size would leave a huge stale ghost as soon as spring-load
-  // fires. Use the pre-maximize geometry up-front so the ghost matches the
-  // node's actual post-spring-load footprint (this mirrors the 0.4.4
-  // behaviour that was lost in the unified-drag refactor).
-  const isMaximized = node.preMaximizeOrigin != null && node.preMaximizeSize != null
-  const effectiveSize: Size = isMaximized && node.preMaximizeSize
-    ? { width: node.preMaximizeSize.width, height: node.preMaximizeSize.height }
-    : { width: node.size.width, height: node.size.height }
-  const effectiveOrigin: Point = isMaximized && node.preMaximizeOrigin
-    ? { x: node.preMaximizeOrigin.x, y: node.preMaximizeOrigin.y }
-    : { x: node.origin.x, y: node.origin.y }
+  const effectiveSize: Size = { width: node.size.width, height: node.size.height }
+  const effectiveOrigin: Point = { x: node.origin.x, y: node.origin.y }
 
   const container = findCanvasContainerForStore(canvasStoreApi)
   if (!container) {
@@ -189,19 +176,6 @@ function measureCanvasNodeGrab(
     y: cursorClient.y - container.rect.top,
   }
   const cursorCanvas = viewToCanvas(localView, zoom, container.viewportOffset)
-  // For a maximized node, project the grab proportionally into the pre-maximize
-  // rect so the cursor stays at the same relative spot inside the (smaller)
-  // ghost — otherwise grabbing the right side of a maximized node would put
-  // the cursor far outside a much smaller pre-maximize ghost.
-  if (isMaximized) {
-    const fx = (cursorCanvas.x - node.origin.x) / Math.max(node.size.width, 1)
-    const fy = (cursorCanvas.y - node.origin.y) / Math.max(node.size.height, 1)
-    return {
-      grab: { x: fx * effectiveSize.width, y: fy * effectiveSize.height },
-      ghostSize: effectiveSize,
-      ghostZoom: zoom,
-    }
-  }
   return {
     grab: { x: cursorCanvas.x - effectiveOrigin.x, y: cursorCanvas.y - effectiveOrigin.y },
     ghostSize: effectiveSize,
diff --git a/src/renderer/panels/CanvasPanel.tsx b/src/renderer/panels/CanvasPanel.tsx
index 767b8a55..affe6e93 100644
--- a/src/renderer/panels/CanvasPanel.tsx
+++ b/src/renderer/panels/CanvasPanel.tsx
@@ -19,6 +19,7 @@ import type { StoreApi } from 'zustand'
 import { useKeepMountedPanelIds } from './keepMountedPanels'
 import { setActivePanel } from '../lib/activePanel'
 import { createDockStore, type DockStore } from '../stores/dockStore'
+import { useOptionalDockStoreApi } from '../stores/DockStoreContext'
 import {
   registerNodeDockStore,
   unregisterNodeDockStore,
@@ -78,6 +79,7 @@ const CanvasNodeWrapper = React.memo(({ nodeId, canvasPanelId, workspaceId, rend
   const firstPanelId = node ? activeDockPanelId(node.dockLayout) : undefined
   const title = useAppStore((s) => firstPanelId ? s.workspaces.find((w) => w.id === workspaceId)?.panels[firstPanelId]?.title : undefined)
   const canvasStoreApi = useCanvasStoreApi()
+  const outerDockStoreApi = useOptionalDockStoreApi()
 
   // ------------------------------------------------------------------
   // Create (or reuse) the per-node DockStore, keyed by canvasPanelId:nodeId
@@ -180,8 +182,10 @@ const CanvasNodeWrapper = React.memo(({ nodeId, canvasPanelId, workspaceId, rend
     <NodeErrorBoundary nodeId={node.id}>
       <CanvasNode
         nodeId={node.id}
+        canvasPanelId={canvasPanelId}
         isFocused={isFocused}
         dockStoreApi={dockStoreApi}
+        outerDockStoreApi={outerDockStoreApi ?? undefined}
         renderPanel={renderPanel}
         title={title}
       />
diff --git a/src/renderer/panels/TerminalPanel.tsx b/src/renderer/panels/TerminalPanel.tsx
index 562c6bfd..7cee4517 100644
--- a/src/renderer/panels/TerminalPanel.tsx
+++ b/src/renderer/panels/TerminalPanel.tsx
@@ -15,7 +15,6 @@
 import { useEffect, useRef, useState, useCallback } from 'react'
 
 import type { TerminalPanelProps } from './types'
-import { isMaximized } from '../../shared/types'
 import { terminalRegistry } from '../lib/terminal/terminalRegistry'
 import { formatTerminalPaste, type DroppedRef } from './terminalDrop'
 import { useAppStore } from '../stores/appStore'
@@ -208,10 +207,7 @@ export default function TerminalPanel({
 
   const isFocused = useOptionalCanvasStoreContext((s) => focusedNodeId(s) === nodeId, false)
   const canvasApi = useOptionalCanvasStoreApi()
-  const zoomLevel = useOptionalCanvasStoreContext((s) => {
-    const node = nodeId ? s.nodes[nodeId] : undefined
-    return node && isMaximized(node) ? 1 : s.zoomLevel
-  }, 1)
+  const zoomLevel = useOptionalCanvasStoreContext((s) => s.zoomLevel, 1)
 
   // -------------------------------------------------------------------------
   // Search handlers
diff --git a/src/renderer/shells/DockWindowShell.tsx b/src/renderer/shells/DockWindowShell.tsx
index a6b81091..66f74491 100644
--- a/src/renderer/shells/DockWindowShell.tsx
+++ b/src/renderer/shells/DockWindowShell.tsx
@@ -434,7 +434,7 @@ export default function DockWindowShell({ workspaceId: initialWorkspaceId }: Doc
           }
         `}</style>
         {/* Full content area — center zone only */}
-        <div data-panel-maximize-root className="flex-1 min-h-0 min-w-0 relative overflow-hidden">
+        <div className="flex-1 min-h-0 min-w-0 relative overflow-hidden">
           <DockZone
             position="center"
             renderPanel={renderPanel}
diff --git a/src/renderer/shells/MainWindowShell.tsx b/src/renderer/shells/MainWindowShell.tsx
index 7fd7c80a..8eb0961b 100644
--- a/src/renderer/shells/MainWindowShell.tsx
+++ b/src/renderer/shells/MainWindowShell.tsx
@@ -18,7 +18,6 @@ import {
   DragOverlay,
 } from '../drag'
 import { LeftSidebarReopen, useLeftChromeInset } from './LeftSidebarReopen'
-import { findZoneForStack } from '../stores/dockTreeUtils'
 
 interface MainWindowShellProps {
   renderPanel: (panelId: string) => React.ReactNode
@@ -45,10 +44,6 @@ export default function MainWindowShell({
   // Nested canvas-node bars are exempt.
   const leftReserve = useLeftChromeInset()
 
-  const maximizedZone = useDockStoreContext((s) => {
-    const position = s.maximizedStackId ? findZoneForStack(s.zones, s.maximizedStackId) : null
-    return position && s.zones[position].visible ? position : null
-  })
   const leftVisible = useDockStoreContext((s) => s.zones.left.visible)
   const bottomVisible = useDockStoreContext((s) => s.zones.bottom.visible)
   const setZoneSize = useDockStoreContext((s) => s.setZoneSize)
@@ -135,7 +130,6 @@ export default function MainWindowShell({
   return (
     <div
       ref={shellRef}
-      data-panel-maximize-root
       className="main-window-shell-root flex flex-col h-full w-full min-h-0 min-w-0 relative"
       style={workspaceAccent ? ({ ['--workspace-accent' as string]: workspaceAccent } as React.CSSProperties) : undefined}
     >
@@ -154,27 +148,26 @@ export default function MainWindowShell({
           no-drag so it stays clickable over the window drag island. */}
       <LeftSidebarReopen />
       {/* Top row: left dock | center dock | right dock */}
-      <div className="flex flex-1 min-h-0 min-w-0" style={maximizedZone === 'bottom' ? { display: 'none' } : undefined}>
+      <div className="flex flex-1 min-h-0 min-w-0">
         {/* Left dock zone */}
         {leftVisible && (
-          <div className="flex min-h-0 shrink-0" style={{ display: maximizedZone && maximizedZone !== 'left' ? 'none' : undefined, flex: maximizedZone === 'left' ? 1 : undefined }}>
+          <div className="flex min-h-0 shrink-0">
             <DockZone
-              fill={maximizedZone === 'left'}
               position="left"
               renderPanel={renderPanel}
               getPanelTitle={getPanelTitle}
               onClosePanel={onClosePanel}
               onClosePanels={onClosePanels}
             />
-            {!maximizedZone && <DockResizeHandle
+            <DockResizeHandle
               direction="horizontal"
               onResize={(delta) => handleZoneResize('left', delta)}
-            />}
+            />
           </div>
         )}
 
         {/* Center dock zone — always visible, flex-1 */}
-        <div className="flex-1 min-h-0 min-w-0 relative overflow-hidden" style={maximizedZone && maximizedZone !== 'center' ? { display: 'none' } : undefined}>
+        <div className="flex-1 min-h-0 min-w-0 relative overflow-hidden">
           <DockZone
             position="center"
             emptyContent={<WorkspaceEmptyState workspaceId={selectedWorkspace?.id ?? ''} />}
@@ -189,13 +182,12 @@ export default function MainWindowShell({
 
       {/* Bottom dock zone */}
       {bottomVisible && (
-        <div className="flex flex-col min-h-0 shrink-0" style={{ display: maximizedZone && maximizedZone !== 'bottom' ? 'none' : undefined, flex: maximizedZone === 'bottom' ? 1 : undefined }}>
-          {!maximizedZone && <DockResizeHandle
+        <div className="flex flex-col min-h-0 shrink-0">
+          <DockResizeHandle
             direction="vertical"
             onResize={(delta) => handleZoneResize('bottom', delta)}
-          />}
+          />
           <DockZone
-            fill={maximizedZone === 'bottom'}
             position="bottom"
             renderPanel={renderPanel}
             getPanelTitle={getPanelTitle}
diff --git a/src/renderer/stores/DockStoreContext.tsx b/src/renderer/stores/DockStoreContext.tsx
index 00bfe624..fd0520e2 100644
--- a/src/renderer/stores/DockStoreContext.tsx
+++ b/src/renderer/stores/DockStoreContext.tsx
@@ -28,6 +28,12 @@ export function useDockStoreApi(): StoreApi<DockStore> {
   return store
 }
 
+/** Canvas panels are also rendered by isolated tests/previews without a dock
+ * host; those callers simply do not offer panel promotion. */
+export function useOptionalDockStoreApi(): StoreApi<DockStore> | null {
+  return useContext(DockStoreContext)
+}
+
 /** Reactive selector hook — reads from the context-provided dock store */
 export function useDockStoreContext<T>(selector: (s: DockStore) => T): T {
   const store = useContext(DockStoreContext)
diff --git a/src/renderer/stores/canvas/nodesSlice.ts b/src/renderer/stores/canvas/nodesSlice.ts
index f7aef789..b9279505 100644
--- a/src/renderer/stores/canvas/nodesSlice.ts
+++ b/src/renderer/stores/canvas/nodesSlice.ts
@@ -1,6 +1,6 @@
 // =============================================================================
 // Nodes slice — node lifecycle (create/remove/move/resize), focus, z-order,
-// maximize, per-node dock layout, and node queries.
+// per-node dock layout, and node queries.
 // =============================================================================
 
 import type { CanvasNodeState } from '../../../shared/types'
@@ -21,7 +21,6 @@ type NodesActions = Pick<
   | 'resizeNode'
   | 'focusNode'
   | 'unfocus'
-  | 'toggleMaximize'
   | 'focusAndCenter'
   | 'moveToFront'
   | 'moveToBack'
@@ -195,44 +194,6 @@ export function createNodesSlice(set: CanvasSet, get: CanvasGet): NodesActions {
       set({ selectionActive: false })
     },
 
-    toggleMaximize(id, _viewportSize) {
-      const state = get()
-      const node = state.nodes[id]
-      if (!node) return
-
-      const isMaximized = node.preMaximizeOrigin != null
-
-      let updated: CanvasNodeState
-      if (isMaximized) {
-        // Restore pre-maximize geometry
-        updated = {
-          ...node,
-          origin: node.preMaximizeOrigin!,
-          size: node.preMaximizeSize!,
-          preMaximizeOrigin: undefined,
-          preMaximizeSize: undefined,
-        }
-      } else {
-        // Full-window presentation preserves the original canvas geometry.
-        updated = {
-          ...node,
-          preMaximizeOrigin: { ...node.origin },
-          preMaximizeSize: { ...node.size },
-        }
-      }
-
-      // Focus the node as well (bump zOrder)
-      updated = { ...updated, zOrder: state.nextZOrder }
-
-      set({
-        nodes: { ...state.nodes, [id]: updated },
-        nextZOrder: state.nextZOrder + 1,
-        selection: [id],
-        selectionActive: true,
-        focusEpoch: state.focusEpoch + 1,
-      })
-    },
-
     nodeForPanel(panelId) {
       const { nodes } = get()
       const found = Object.values(nodes).find((n) => collectPanelIds(n.dockLayout).includes(panelId))
diff --git a/src/renderer/stores/canvas/sanitizeNodes.test.ts b/src/renderer/stores/canvas/sanitizeNodes.test.ts
index f89dcb08..61755b52 100644
--- a/src/renderer/stores/canvas/sanitizeNodes.test.ts
+++ b/src/renderer/stores/canvas/sanitizeNodes.test.ts
@@ -70,15 +70,6 @@ describe('sanitizeLoadedCanvasNodes', () => {
     expect(Object.keys(nodes)).toEqual(['good'])
   })
 
-  it('strips malformed pre-maximize geometry rather than risk a second crash', () => {
-    const { nodes, repaired } = sanitizeLoadedCanvasNodes({
-      n1: { ...valid, preMaximizeOrigin: { x: 1, y: 2 }, preMaximizeSize: { width: 0, height: 0 } },
-    })
-    expect(repaired).toEqual(['n1'])
-    expect(nodes.n1.preMaximizeSize).toBeUndefined()
-    expect(nodes.n1.preMaximizeOrigin).toEqual({ x: 1, y: 2 })
-  })
-
   it('falls back to the map key when a node has no id', () => {
     const { nodes } = sanitizeLoadedCanvasNodes({ key1: { ...valid, id: undefined } })
     expect(nodes.key1.id).toBe('key1')
diff --git a/src/renderer/stores/canvas/sanitizeNodes.ts b/src/renderer/stores/canvas/sanitizeNodes.ts
index 60dfe2d2..7c92ec41 100644
--- a/src/renderer/stores/canvas/sanitizeNodes.ts
+++ b/src/renderer/stores/canvas/sanitizeNodes.ts
@@ -107,13 +107,17 @@ export function sanitizeLoadedCanvasNodes(
       dropped.push(key)
       continue
     }
-    const v = value as Partial<CanvasNodeState>
+    const legacy = value as Partial<CanvasNodeState> & {
+      preMaximizeOrigin?: Point
+      preMaximizeSize?: Size
+    }
+    const { preMaximizeOrigin: _legacyOrigin, preMaximizeSize: _legacySize, ...v } = legacy
     if (!isValidDockLayout(v.dockLayout)) {
       dropped.push(key)
       continue
     }
 
-    let touched = false
+    let touched = _legacyOrigin != null || _legacySize != null
     const repair = <T>(ok: boolean, good: T, fallback: T): T => {
       if (ok) return good
       touched = true
@@ -132,18 +136,6 @@ export function sanitizeLoadedCanvasNodes(
       creationIndex: repair(isFiniteNumber(v.creationIndex), v.creationIndex as number, nextC++),
     }
 
-    // A maximized node carries pre-maximize geometry that resize/restore code
-    // reads; if it's malformed, drop it back to a normal (un-maximized) node
-    // rather than risk a second crash.
-    if (node.preMaximizeOrigin != null && !isValidPoint(node.preMaximizeOrigin)) {
-      delete node.preMaximizeOrigin
-      touched = true
-    }
-    if (node.preMaximizeSize != null && !isValidSize(node.preMaximizeSize)) {
-      delete node.preMaximizeSize
-      touched = true
-    }
-
     nodes[key] = node
     if (touched) repaired.push(key)
   }
diff --git a/src/renderer/stores/canvas/selectionModel.test.ts b/src/renderer/stores/canvas/selectionModel.test.ts
index af4a82b7..0d4c4c20 100644
--- a/src/renderer/stores/canvas/selectionModel.test.ts
+++ b/src/renderer/stores/canvas/selectionModel.test.ts
@@ -231,7 +231,7 @@ describe('unfocus', () => {
 })
 
 // =============================================================================
-// The activating actions — focusNode / focusAndCenter / toggleMaximize / addNode
+// The activating actions — focusNode / focusAndCenter / addNode
 // (existing-node branch) all collapse to [id] + active and bump zOrder/epoch.
 // =============================================================================
 
@@ -251,17 +251,6 @@ describe('activating actions collapse to a single active selection', () => {
     expectInvariant(s)
   })
 
-  it('toggleMaximize collapses to [id] + active', () => {
-    const { store, a, b } = addThree()
-    store.getState().setContainerSize({ width: 800, height: 600 })
-    store.getState().selectNodes([a, b])
-    store.getState().toggleMaximize(b, { width: 800, height: 600 })
-    const s = store.getState()
-    expect(s.selection).toEqual([b])
-    expect(focusedNodeId(s)).toBe(b)
-    expectInvariant(s)
-  })
-
   it("addNode's existing-node branch collapses to that node + active", () => {
     const { store, a } = addThree()
     store.getState().selectNodes([a]) // deactivated
diff --git a/src/renderer/stores/canvas/storeTypes.ts b/src/renderer/stores/canvas/storeTypes.ts
index e45de653..6501ebb0 100644
--- a/src/renderer/stores/canvas/storeTypes.ts
+++ b/src/renderer/stores/canvas/storeTypes.ts
@@ -110,7 +110,6 @@ export interface CanvasStoreActions {
   resizeNode: (id: CanvasNodeId, size: Size, origin?: Point) => void
   focusNode: (id: CanvasNodeId) => void
   unfocus: () => void
-  toggleMaximize: (id: CanvasNodeId, viewportSize: Size) => void
   setZoom: (level: number) => void
   setViewportOffset: (offset: Point) => void
   setZoomAndOffset: (zoom: number, offset: Point) => void
diff --git a/src/renderer/stores/canvasStore.lifecycle.test.ts b/src/renderer/stores/canvasStore.lifecycle.test.ts
index eae76d22..d5b03250 100644
--- a/src/renderer/stores/canvasStore.lifecycle.test.ts
+++ b/src/renderer/stores/canvasStore.lifecycle.test.ts
@@ -237,41 +237,6 @@ describe('viewport math', () => {
     expect(store.getState().zoomLevel).toBe(1.5)
   })
 
-  it('toggleMaximize preserves canvas geometry and restores exactly on toggle back', () => {
-    const store = createCanvasStore()
-    const id = store.getState().addNode('p', 'editor', { x: 100, y: 100 }, { width: 300, height: 200 })
-    store.getState().setContainerSize({ width: 1200, height: 800 })
-    store.getState().setZoomAndOffset(1, { x: 0, y: 0 })
-
-    store.getState().toggleMaximize(id, { width: 1200, height: 800 })
-    const maxed = store.getState().nodes[id]
-    expect(maxed.origin).toEqual({ x: 100, y: 100 })
-    expect(maxed.size).toEqual({ width: 300, height: 200 })
-    expect(maxed.preMaximizeOrigin).toEqual({ x: 100, y: 100 })
-    expect(focusedNodeId(store.getState())).toBe(id)
-
-    store.getState().toggleMaximize(id, { width: 1200, height: 800 })
-    const restored = store.getState().nodes[id]
-    expect(restored.origin).toEqual({ x: 100, y: 100 })
-    expect(restored.size).toEqual({ width: 300, height: 200 })
-    expect(restored.preMaximizeOrigin).toBeUndefined()
-    expect(restored.preMaximizeSize).toBeUndefined()
-  })
-
-  it.each([0.5, 1.04, 2])('maximize preserves canvas geometry at zoom %s', (zoom) => {
-    const store = createCanvasStore()
-    const id = store.getState().addNode('p', 'editor', { x: 100, y: 100 }, { width: 300, height: 200 })
-    store.getState().setContainerSize({ width: 1200, height: 800 })
-    store.getState().setZoomAndOffset(zoom, { x: 137, y: -83 })
-
-    // The canvas can be smaller than the window because of sidebars/docks.
-    store.getState().toggleMaximize(id, { width: 1600, height: 1000 })
-    const node = store.getState().nodes[id]
-    expect(node.origin).toEqual({ x: 100, y: 100 })
-    expect(node.size).toEqual({ width: 300, height: 200 })
-    expect(store.getState().zoomLevel).toBe(zoom)
-    expect(store.getState().viewportOffset).toEqual({ x: 137, y: -83 })
-  })
 })
 
 describe('undo/redo across a bulk delete', () => {
@@ -491,8 +456,6 @@ describe('degenerate inputs and limits', () => {
     store.getState().togglePin('ghost')
     store.getState().moveToFront('ghost')
     store.getState().setNodeAnimationState('ghost', 'idle')
-    store.getState().toggleMaximize('ghost', { width: 100, height: 100 })
-
     expect(store.getState().nodes).toEqual(nodesBefore)
     expect(store.getState().history).toHaveLength(historyLen)
     expect(focusedNodeId(store.getState())).toBeNull()
diff --git a/src/renderer/stores/canvasStore.test.ts b/src/renderer/stores/canvasStore.test.ts
index 1dc429a0..dd8fb5d5 100644
--- a/src/renderer/stores/canvasStore.test.ts
+++ b/src/renderer/stores/canvasStore.test.ts
@@ -269,15 +269,6 @@ describe('canvasStore — focusEpoch bumps on focus actions', () => {
     expect(store.getState().focusEpoch).toBe(before)
   })
 
-  it('toggleMaximize bumps focusEpoch', () => {
-    const store = createCanvasStore()
-    const id = store.getState().addNode('p1', 'terminal', { x: 0, y: 0 }, { width: 100, height: 80 })
-    store.getState().setContainerSize({ width: 800, height: 600 })
-
-    const before = store.getState().focusEpoch
-    store.getState().toggleMaximize(id, { width: 800, height: 600 })
-    expect(store.getState().focusEpoch).toBe(before + 1)
-  })
 })
 
 // =============================================================================
diff --git a/src/renderer/stores/canvasStore.ts b/src/renderer/stores/canvasStore.ts
index 69b234c4..93d45bd1 100644
--- a/src/renderer/stores/canvasStore.ts
+++ b/src/renderer/stores/canvasStore.ts
@@ -338,7 +338,7 @@ export function selectVisibleNodeIds(
 
   const result: string[] = []
   for (const n of sorted) {
-    if (n.preMaximizeOrigin != null || n.id === focusedNodeId || n.isPinned || keepAlive.has(n.id)) {
+    if (n.id === focusedNodeId || n.isPinned || keepAlive.has(n.id)) {
       result.push(n.id)
       continue
     }
diff --git a/src/renderer/stores/canvasVisibleNodes.test.tsx b/src/renderer/stores/canvasVisibleNodes.test.tsx
index 9cac2a03..268b84a3 100644
--- a/src/renderer/stores/canvasVisibleNodes.test.tsx
+++ b/src/renderer/stores/canvasVisibleNodes.test.tsx
@@ -54,22 +54,4 @@ describe('useVisibleNodeIds zoom settling', () => {
     expect(host.firstElementChild?.getAttribute('data-ids')).toBe(`${first},${second}`)
   })
 
-  it('keeps a maximized node mounted after losing focus in a collapsed canvas', () => {
-    const store = createCanvasStore()
-    store.getState().setContainerSize({ width: 800, height: 600 })
-    const id = store.getState().addNode('terminal', 'terminal', { x: 200, y: 200 }, { width: 640, height: 400 })
-    const Probe = () => <div data-ids={useVisibleNodeIds(store, new Set()).join(',')} />
-    act(() => root.render(<Probe />))
-    act(() => {
-      store.getState().toggleMaximize(id, { width: 800, height: 600 })
-      store.getState().setContainerSize({ width: 800, height: 1 })
-      store.getState().unfocus()
-    })
-    expect(host.firstElementChild?.getAttribute('data-ids')).toBe(id)
-    act(() => {
-      store.getState().toggleMaximize(id, { width: 800, height: 600 })
-      store.getState().unfocus()
-    })
-    expect(host.firstElementChild?.getAttribute('data-ids')).toBe('')
-  })
 })
diff --git a/src/renderer/stores/dockStore.maximize.test.ts b/src/renderer/stores/dockStore.maximize.test.ts
deleted file mode 100644
index 44cf48b5..00000000
--- a/src/renderer/stores/dockStore.maximize.test.ts
+++ /dev/null
@@ -1,48 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { createDockStore } from './dockStore'
-
-function fixture() {
-  const store = createDockStore()
-  store.getState().dockPanel('a', 'center')
-  const a = store.getState().getPanelLocation('a')!
-  if (a.type !== 'dock') throw new Error('Expected dock location')
-  store.getState().dockPanel('b', 'center', { type: 'split', stackId: a.stackId, edge: 'right' })
-  const b = store.getState().getPanelLocation('b')!
-  if (b.type !== 'dock') throw new Error('Expected dock location')
-  store.getState().toggleStackMaximized(a.stackId)
-  return { store, a: a.stackId, b: b.stackId }
-}
-
-describe('maximized dock lifecycle', () => {
-  it('reveals a sibling selected through shared panel navigation', () => {
-    const { store, b } = fixture()
-    store.getState().setActiveTab(b, 0)
-    expect(store.getState().maximizedStackId).toBeNull()
-  })
-  it('keeps the current pane maximized when selecting its tab or an invalid destination', () => {
-    const { store, a, b } = fixture()
-    store.getState().setActiveTab(a, 0)
-    store.getState().setActiveTab(b, 42)
-    expect(store.getState().maximizedStackId).toBe(a)
-  })
-  it('reveals a new foreground tab while leaving background creation alone', () => {
-    const { store, a, b } = fixture()
-    store.getState().dockPanel('background', 'center', { type: 'tab', stackId: b }, false)
-    expect(store.getState().maximizedStackId).toBe(a)
-    store.getState().dockPanel('foreground', 'center', { type: 'tab', stackId: b })
-    expect(store.getState().maximizedStackId).toBeNull()
-  })
-  it('reveals a different zone opened by the user', () => {
-    const { store } = fixture()
-    store.getState().dockPanel('side', 'left', undefined, false)
-    store.getState().toggleZone('left')
-    expect(store.getState().maximizedStackId).toBeNull()
-  })
-  it.each(['undock', 'collapse', 'move'] as const)('clears maximization when %s removes the maximized stack', operation => {
-    const { store, a, b } = fixture()
-    if (operation === 'undock') store.getState().undockPanel('a')
-    if (operation === 'collapse') store.getState().collapseStack(a)
-    if (operation === 'move') store.getState().moveTab('a', a, b)
-    expect(store.getState().maximizedStackId).toBeNull()
-  })
-})
diff --git a/src/renderer/stores/dockStore.presentation.test.ts b/src/renderer/stores/dockStore.presentation.test.ts
new file mode 100644
index 00000000..cfcbb7c2
--- /dev/null
+++ b/src/renderer/stores/dockStore.presentation.test.ts
@@ -0,0 +1,258 @@
+import { describe, expect, it } from 'vitest'
+import { createDockStore } from './dockStore'
+
+function fixture() {
+  const store = createDockStore()
+  store.getState().dockPanel('a', 'center')
+  const a = store.getState().getPanelLocation('a')!
+  if (a.type !== 'dock') throw new Error('Expected dock location')
+  store.getState().dockPanel('b', 'center', { type: 'split', stackId: a.stackId, edge: 'right' })
+  return { store, stackId: a.stackId }
+}
+
+function promotedFixture() {
+  const store = createDockStore()
+  store.getState().dockPanel('canvas', 'center')
+  const canvas = store.getState().getPanelLocation('canvas')!
+  if (canvas.type !== 'dock') throw new Error('Expected dock location')
+  store.getState().dockPanel('peer', 'center', {
+    type: 'split', stackId: canvas.stackId, edge: 'right',
+  })
+  const peer = store.getState().getPanelLocation('peer')!
+  if (peer.type !== 'dock') throw new Error('Expected dock location')
+  const restoreLayout = store.getState().zones.center.layout!
+  if (restoreLayout.type !== 'split') throw new Error('Expected split layout')
+  store.getState().dockPanel('promoted', 'center', { type: 'tab', stackId: canvas.stackId })
+  store.getState().beginPresentation({
+    stackId: canvas.stackId,
+    panelId: 'promoted',
+    zone: 'center',
+    restoreLayout,
+    expectedLayout: store.getState().zones.center.layout!,
+  })
+  return {
+    store,
+    stackId: canvas.stackId,
+    peerStackId: peer.stackId,
+    splitId: restoreLayout.id,
+  }
+}
+
+type PromotedFixture = ReturnType<typeof promotedFixture>
+
+const safeWhilePresented: Array<[string, (fixture: PromotedFixture) => void]> = [
+  ['selecting the canvas tab', ({ store, stackId }) => store.getState().setActiveTab(stackId, 0)],
+  ['selecting the promoted tab again', ({ store, stackId }) => store.getState().setActiveTab(stackId, 1)],
+  ['resizing the surrounding split', ({ store, splitId }) => store.getState().setSplitRatio(splitId, [0.3, 0.7])],
+  ['resizing a dock zone', ({ store }) => store.getState().setZoneSize('right', 420)],
+  ['toggling an unrelated dock zone', ({ store }) => store.getState().toggleZone('right')],
+  ['adding a panel to another dock zone', ({ store }) => store.getState().dockPanel('unrelated', 'right')],
+  ['taking a persistence snapshot', ({ store }) => { store.getState().getSnapshot() }],
+]
+
+const invalidatingWhilePresented: Array<[string, (fixture: PromotedFixture) => void]> = [
+  ['adding a tab beside the promoted panel', ({ store, stackId }) => {
+    store.getState().dockPanel('new', 'center', { type: 'tab', stackId })
+  }],
+  ['adding a background tab beside the promoted panel', ({ store, stackId }) => {
+    store.getState().dockPanel('new', 'center', { type: 'tab', stackId }, false)
+  }],
+  ['removing the promoted panel', ({ store }) => store.getState().undockPanel('promoted')],
+  ['removing the canvas tab', ({ store }) => store.getState().undockPanel('canvas')],
+  ['removing a sibling split panel', ({ store }) => store.getState().undockPanel('peer')],
+  ['reordering the promoted panel', ({ store, stackId }) => {
+    store.getState().moveTab('promoted', stackId, stackId, 0)
+  }],
+  ['moving the promoted panel to another stack', ({ store, stackId, peerStackId }) => {
+    store.getState().moveTab('promoted', stackId, peerStackId)
+  }],
+  ['moving another panel into the presented stack', ({ store, stackId, peerStackId }) => {
+    store.getState().moveTab('peer', peerStackId, stackId)
+  }],
+  ['splitting the promoted panel', ({ store, stackId }) => {
+    store.getState().dockPanel('promoted', 'center', { type: 'split', stackId, edge: 'right' })
+  }],
+  ['splitting a sibling panel', ({ store, peerStackId }) => {
+    store.getState().dockPanel('new', 'center', { type: 'split', stackId: peerStackId, edge: 'bottom' })
+  }],
+  ['collapsing the presented stack', ({ store, stackId }) => store.getState().collapseStack(stackId)],
+  ['collapsing a sibling stack', ({ store, peerStackId }) => store.getState().collapseStack(peerStackId)],
+]
+
+describe('dock presentation', () => {
+  it('merges a split into tabs and restores the original tree', () => {
+    const { store, stackId } = fixture()
+    const original = store.getState().zones.center.layout
+    store.getState().mergeSplitToStack(stackId)
+    expect(store.getState().zones.center.layout).toMatchObject({
+      type: 'tabs', panelIds: ['a', 'b'], activeIndex: 0,
+    })
+    expect(store.getState().canRestorePresentation(stackId)).toBe(true)
+    expect(store.getState().restorePresentation(stackId)).toBe(true)
+    expect(store.getState().zones.center.layout).toBe(original)
+  })
+
+  it('discards restore permanently after the merged topology changes', () => {
+    const { store, stackId } = fixture()
+    store.getState().mergeSplitToStack(stackId)
+    store.getState().dockPanel('new', 'center', { type: 'tab', stackId })
+    expect(store.getState().presentation).toBeNull()
+    expect(store.getState().canRestorePresentation(stackId)).toBe(false)
+    expect(store.getState().restorePresentation(stackId)).toBe(false)
+    expect(store.getState().getPanelLocation('new')).toBeDefined()
+  })
+
+  it('does not restore after a promoted panel is moved and moved back', () => {
+    const store = createDockStore()
+    store.getState().dockPanel('canvas', 'center')
+    const location = store.getState().getPanelLocation('canvas')!
+    if (location.type !== 'dock') throw new Error('Expected dock location')
+    const restoreLayout = store.getState().zones.center.layout!
+    store.getState().dockPanel('promoted', 'center', { type: 'tab', stackId: location.stackId })
+    const expectedLayout = store.getState().zones.center.layout!
+    store.getState().beginPresentation({
+      stackId: location.stackId,
+      panelId: 'promoted',
+      zone: 'center',
+      restoreLayout,
+      expectedLayout,
+    })
+
+    store.getState().undockPanel('promoted')
+    expect(store.getState().presentation).toBeNull()
+    store.getState().dockPanel('promoted', 'right')
+    store.getState().dockPanel('promoted', 'center', { type: 'tab', stackId: location.stackId })
+    expect(store.getState().canRestorePresentation(location.stackId)).toBe(false)
+  })
+
+  it('discards restore when a promoted panel is split', () => {
+    const store = createDockStore()
+    store.getState().dockPanel('canvas', 'center')
+    const location = store.getState().getPanelLocation('canvas')!
+    if (location.type !== 'dock') throw new Error('Expected dock location')
+    const restoreLayout = store.getState().zones.center.layout!
+    store.getState().dockPanel('promoted', 'center', { type: 'tab', stackId: location.stackId })
+    store.getState().beginPresentation({
+      stackId: location.stackId,
+      panelId: 'promoted',
+      zone: 'center',
+      restoreLayout,
+      expectedLayout: store.getState().zones.center.layout!,
+    })
+
+    store.getState().dockPanel('promoted', 'center', {
+      type: 'split',
+      stackId: location.stackId,
+      edge: 'right',
+    })
+    expect(store.getState().presentation).toBeNull()
+    expect(store.getState().zones.center.layout?.type).toBe('split')
+  })
+
+  it('allows tab selection while preserving reversibility', () => {
+    const { store, stackId } = fixture()
+    store.getState().mergeSplitToStack(stackId)
+    store.getState().setActiveTab(stackId, 1)
+    expect(store.getState().canRestorePresentation(stackId)).toBe(true)
+  })
+
+  it.each(safeWhilePresented)('keeps restore after %s', (_label, mutate) => {
+    const current = promotedFixture()
+    mutate(current)
+    expect(current.store.getState().presentation).not.toBeNull()
+    expect(current.store.getState().canRestorePresentation(current.stackId)).toBe(true)
+  })
+
+  it.each(invalidatingWhilePresented)('permanently discards restore after %s', (_label, mutate) => {
+    const current = promotedFixture()
+    mutate(current)
+    expect(current.store.getState().presentation).toBeNull()
+    expect(current.store.getState().canRestorePresentation(current.stackId)).toBe(false)
+  })
+
+  it('discards immediately when the external canvas source is no longer restorable', () => {
+    const current = promotedFixture()
+    const presentation = current.store.getState().presentation!
+    current.store.getState().discardPresentation()
+    current.store.getState().beginPresentation({
+      ...presentation,
+      canRestoreExternal: () => false,
+    })
+    expect(current.store.getState().presentation).toBeNull()
+  })
+
+  it('disposes external invalidation tracking exactly once', () => {
+    const current = promotedFixture()
+    const presentation = current.store.getState().presentation!
+    let disposals = 0
+    current.store.setState({
+      presentation: { ...presentation, dispose: () => { disposals += 1 } },
+    })
+    current.store.getState().undockPanel('promoted')
+    expect(disposals).toBe(1)
+  })
+
+  it('discards and disposes presentation state when a snapshot is restored', () => {
+    const current = promotedFixture()
+    const snapshot = current.store.getState().getSnapshot()
+    const presentation = current.store.getState().presentation!
+    let disposals = 0
+    current.store.setState({
+      presentation: { ...presentation, dispose: () => { disposals += 1 } },
+    })
+    current.store.getState().restoreSnapshot(snapshot)
+    expect(current.store.getState().presentation).toBeNull()
+    expect(disposals).toBe(1)
+  })
+
+  it('keeps the transaction when restore is requested by the wrong stack', () => {
+    const current = promotedFixture()
+    expect(current.store.getState().restorePresentation(current.peerStackId)).toBe(false)
+    expect(current.store.getState().presentation).not.toBeNull()
+  })
+
+  it('runs external restore and disposes tracking exactly once on valid restore', () => {
+    const current = promotedFixture()
+    const presentation = current.store.getState().presentation!
+    let restorations = 0
+    let disposals = 0
+    current.store.setState({
+      presentation: {
+        ...presentation,
+        restoreExternal: () => { restorations += 1 },
+        dispose: () => { disposals += 1 },
+      },
+    })
+    expect(current.store.getState().restorePresentation(current.stackId)).toBe(true)
+    expect(restorations).toBe(1)
+    expect(disposals).toBe(1)
+    expect(current.store.getState().presentation).toBeNull()
+  })
+
+  it('disposes tracking on explicit discard', () => {
+    const current = promotedFixture()
+    const presentation = current.store.getState().presentation!
+    let disposals = 0
+    current.store.setState({
+      presentation: { ...presentation, dispose: () => { disposals += 1 } },
+    })
+    current.store.getState().discardPresentation()
+    expect(disposals).toBe(1)
+    expect(current.store.getState().presentation).toBeNull()
+  })
+
+  it('does not replace or nest an active presentation', () => {
+    const current = promotedFixture()
+    const presentation = current.store.getState().presentation
+    const layout = current.store.getState().zones.center.layout
+    current.store.getState().mergeSplitToStack(current.peerStackId)
+    current.store.getState().beginPresentation({
+      stackId: 'replacement',
+      zone: 'center',
+      restoreLayout: layout!,
+      expectedLayout: layout!,
+    })
+    expect(current.store.getState().presentation).toBe(presentation)
+    expect(current.store.getState().zones.center.layout).toBe(layout)
+  })
+})
diff --git a/src/renderer/stores/dockStore.ts b/src/renderer/stores/dockStore.ts
index de073dba..aa4e0267 100644
--- a/src/renderer/stores/dockStore.ts
+++ b/src/renderer/stores/dockStore.ts
@@ -157,17 +157,42 @@ function insertIntoSplit(
   }
 }
 
+function collectPanelIdsInTree(node: DockLayoutNode): string[] {
+  if (node.type === 'tabs') return [...node.panelIds]
+  return node.children.flatMap(collectPanelIdsInTree)
+}
+
 // -----------------------------------------------------------------------------
 // Store interface
 // -----------------------------------------------------------------------------
 
 interface DockStoreState {
-  maximizedStackId: string | null
+  presentation: DockPresentation | null
   zones: WindowDockState
 }
 
+export interface DockPresentation {
+  /** The real stack containing the presented panel(s). */
+  stackId: string
+  /** Set for a panel promoted out of a canvas. Split merges apply to the stack. */
+  panelId?: string
+  zone: DockZonePosition
+  /** Layout before the structural transformation. */
+  restoreLayout: DockLayoutNode
+  /** Layout produced by the transformation. Used to reject unsafe restores. */
+  expectedLayout: DockLayoutNode
+  /** Canvas promotion has a second source tree which must still be unchanged. */
+  canRestoreExternal?: () => boolean
+  restoreExternal?: () => void
+  dispose?: () => void
+}
+
 interface DockStoreActions {
-  toggleStackMaximized: (stackId: string) => void
+  mergeSplitToStack: (stackId: string) => void
+  beginPresentation: (presentation: DockPresentation) => void
+  discardPresentation: () => void
+  canRestorePresentation: (stackId: string) => boolean
+  restorePresentation: (stackId: string) => boolean
   // Zone visibility
   toggleZone: (position: DockZonePosition) => void
   setZoneSize: (position: DockZonePosition, size: number) => void
@@ -197,12 +222,21 @@ interface DockStoreActions {
 
 export type DockStore = DockStoreState & DockStoreActions
 
-/** Keep transient maximization valid after layout changes and reveal explicit destinations. */
-function updateDockZones(state: DockStoreState, zones: WindowDockState, revealStackId?: string): DockStoreState {
-  const maximizedZone = state.maximizedStackId && findZoneForStack(zones, state.maximizedStackId)
-  const keepMaximized = maximizedZone && zones[maximizedZone].visible
-    && (!revealStackId || revealStackId === state.maximizedStackId)
-  return { zones, maximizedStackId: keepMaximized ? state.maximizedStackId : null }
+/** Active-tab changes are harmless, but any structural difference makes a
+ * presentation unsafe to reverse. */
+function samePresentationLayout(a: DockLayoutNode | null, b: DockLayoutNode | null): boolean {
+  if (!a || !b) return a === b
+  if (a.type !== b.type || a.id !== b.id) return false
+  if (a.type === 'tabs' && b.type === 'tabs') {
+    return a.panelIds.length === b.panelIds.length
+      && a.panelIds.every((panelId, index) => panelId === b.panelIds[index])
+  }
+  if (a.type === 'split' && b.type === 'split') {
+    return a.direction === b.direction
+      && a.children.length === b.children.length
+      && a.children.every((child, index) => samePresentationLayout(child, b.children[index]))
+  }
+  return false
 }
 
 // -----------------------------------------------------------------------------
@@ -210,11 +244,70 @@ function updateDockZones(state: DockStoreState, zones: WindowDockState, revealSt
 // -----------------------------------------------------------------------------
 
 export function createDockStore(initialState?: DockStateSnapshot) {
-  return create<DockStore>((set, get) => ({
+  const store = create<DockStore>((set, get) => ({
   zones: initialState?.zones ?? createDefaultDockState(),
-  maximizedStackId: null,
-  toggleStackMaximized(stackId) {
-    set((state) => ({ maximizedStackId: state.maximizedStackId === stackId ? null : stackId }))
+  presentation: null,
+  mergeSplitToStack(stackId) {
+    set((state) => {
+      if (state.presentation) return state
+      const zone = findZoneForStack(state.zones, stackId)
+      if (!zone) return state
+      const layout = state.zones[zone].layout
+      const target = findTabStack(layout, stackId)
+      if (!layout || layout.type !== 'split' || !target) return state
+
+      const panelIds = collectPanelIdsInTree(layout)
+      const activePanelId = target.panelIds[target.activeIndex] ?? target.panelIds[0]
+      const merged: DockTabStack = {
+        type: 'tabs',
+        id: target.id,
+        panelIds,
+        activeIndex: Math.max(0, panelIds.indexOf(activePanelId)),
+      }
+      return {
+        zones: {
+          ...state.zones,
+          [zone]: { ...state.zones[zone], layout: merged },
+        },
+        presentation: {
+          stackId: merged.id,
+          zone,
+          restoreLayout: layout,
+          expectedLayout: merged,
+        },
+      }
+    })
+  },
+  beginPresentation(presentation) {
+    set((state) => state.presentation ? state : { presentation })
+  },
+  discardPresentation() {
+    get().presentation?.dispose?.()
+    set({ presentation: null })
+  },
+  canRestorePresentation(stackId) {
+    const state = get()
+    const presentation = state.presentation
+    if (!presentation || presentation.stackId !== stackId) return false
+    return samePresentationLayout(state.zones[presentation.zone].layout, presentation.expectedLayout)
+      && (presentation.canRestoreExternal?.() ?? true)
+  },
+  restorePresentation(stackId) {
+    if (!get().canRestorePresentation(stackId)) return false
+    const presentation = get().presentation!
+    presentation.dispose?.()
+    presentation.restoreExternal?.()
+    set((state) => ({
+      zones: {
+        ...state.zones,
+        [presentation.zone]: {
+          ...state.zones[presentation.zone],
+          layout: presentation.restoreLayout,
+        },
+      },
+      presentation: null,
+    }))
+    return true
   },
 
   // --- Zone visibility ---
@@ -225,8 +318,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
         ...state.zones,
         [position]: { ...state.zones[position], visible: !state.zones[position].visible },
       }
-      const revealStack = zones[position].visible ? findFirstTabStack(zones[position].layout) : null
-      return updateDockZones(state, zones, revealStack?.id)
+      return { zones, presentation: state.presentation }
     })
   },
 
@@ -343,8 +435,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
         ...state.zones,
         [zone]: { ...zoneState, visible: activate ? true : zoneState.visible, layout: newLayout },
       }
-      const destination = activate ? findStackContainingPanelAcrossZones(zones, panelId) : null
-      return updateDockZones(state, zones, destination?.id)
+      return { zones, presentation: state.presentation }
     })
   },
 
@@ -362,7 +453,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
 
       const newLayout = removePanelFromTree(zoneState.layout, panelId)
 
-      return updateDockZones(state, {
+      return { zones: {
         ...state.zones,
         [zone]: {
           ...zoneState,
@@ -370,7 +461,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
           // Auto-hide zone if it's now empty (never hide center)
           visible: zone === 'center' ? true : (newLayout !== null ? zoneState.visible : false),
         },
-      })
+      }, presentation: state.presentation }
     })
   },
 
@@ -427,7 +518,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
         }
       }
 
-      return updateDockZones(state, zones, toStackId)
+      return { zones, presentation: state.presentation }
     })
   },
 
@@ -444,7 +535,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
             ...zoneState,
             layout: replaceInTree(zoneState.layout, stackId, updated),
           }
-          return updateDockZones(state, zones, stackId)
+          return { zones, presentation: state.presentation }
         }
       }
       return state
@@ -510,7 +601,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
         break
       }
 
-      return updateDockZones(state, zones)
+      return { zones, presentation: state.presentation }
     })
   },
 
@@ -531,12 +622,31 @@ export function createDockStore(initialState?: DockStateSnapshot) {
   },
 
   restoreSnapshot(snapshot) {
+    get().presentation?.dispose?.()
     set({
       zones: snapshot.zones,
-      maximizedStackId: null,
+      presentation: null,
     })
   },
-}))
+  }))
+
+  // Presentation is a one-shot reverse transaction, not a mode. The first
+  // incompatible structural change consumes it permanently. In particular,
+  // moving or splitting a panel promoted from a canvas must not allow Restore
+  // to reappear if the user later happens to recreate the old topology.
+  store.subscribe((state) => {
+    const presentation = state.presentation
+    if (!presentation) return
+    const outerUnchanged = samePresentationLayout(
+      state.zones[presentation.zone].layout,
+      presentation.expectedLayout,
+    )
+    if (!outerUnchanged || !(presentation.canRestoreExternal?.() ?? true)) {
+      state.discardPresentation()
+    }
+  })
+
+  return store
 }
 
 // -----------------------------------------------------------------------------
diff --git a/src/shared/electron-api.d.ts b/src/shared/electron-api.d.ts
index 113e7f95..f306017d 100644
--- a/src/shared/electron-api.d.ts
+++ b/src/shared/electron-api.d.ts
@@ -720,6 +720,7 @@ export interface ElectronAPI {
   getRecentScreenshot(): Promise<RecentScreenshot[]>
   onRecentScreenshotChanged(callback: (screenshot: RecentScreenshot[]) => void): () => void
   dragRecentScreenshot(id: string): Promise<void>
+  readRecentScreenshot(id: string): Promise<string>
   saveRecentScreenshot(id: string, dataUrl: string): Promise<RecentScreenshot>
   /** Initiate a native OS file drag from the renderer. */
   nativeFileDrag(filePath: string): Promise<void>
diff --git a/src/shared/ipc-channels.ts b/src/shared/ipc-channels.ts
index 6cbf686f..6aa096a3 100644
--- a/src/shared/ipc-channels.ts
+++ b/src/shared/ipc-channels.ts
@@ -447,3 +447,4 @@ export const REMOTE_CONNECTIONS_REMOVE = 'remote-connections:remove'
 export const REMOTE_CONNECTIONS_CHANGED = 'remote-connections:changed'
 
 export const RECENT_SCREENSHOT_SAVE = 'recentScreenshot:save'
+export const RECENT_SCREENSHOT_READ = 'recentScreenshot:read'
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 8c2b6d1c..d25ea39d 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -47,8 +47,6 @@ export interface CanvasNodeState {
   size: Size
   zOrder: number
   creationIndex: number
-  preMaximizeOrigin?: Point
-  preMaximizeSize?: Size
   isPinned?: boolean
   /** Per-node dock layout tree — what's actually rendered inside the node.
    *  Each canvas node owns a private DockStore whose `center` zone holds this
@@ -58,11 +56,6 @@ export interface CanvasNodeState {
   animationState?: 'entering' | 'exiting' | 'idle'
 }
 
-/** Computed helper — mirrors the Swift `isMaximized` computed property. */
-export function isMaximized(node: CanvasNodeState): boolean {
-  return node.preMaximizeOrigin != null
-}
-
 // -----------------------------------------------------------------------------
 // Panel state (renderer-side representation)
 // -----------------------------------------------------------------------------

From 97e15d30c0381ba4ce9889ab8cea66d2491e96fd Mon Sep 17 00:00:00 2001
From: Anton <antonhorn@icloud.com>
Date: Fri, 11 Sep 2026 11:42:46 +0200
Subject: [PATCH 6/7] Harden dock layout rules and test coverage

---
 docs/dock-rules.md                            |  55 +++++
 e2e/detached-panels.spec.ts                   |   1 +
 e2e/dock-rules.spec.ts                        | 200 ++++++++++++++++++
 e2e/drag-canvas-into-canvas.spec.ts           |  37 ++--
 e2e/drag-move.spec.ts                         |  10 +-
 e2e/drag-split.spec.ts                        |   2 +
 e2e/fixtures/electron-app.ts                  |  20 ++
 .../canvas/RecentScreenshotButton.test.tsx    |  23 ++
 .../canvas/RecentScreenshotButton.tsx         |   2 +-
 src/renderer/canvas/ScreenshotDrawing.tsx     |   2 +-
 src/renderer/lib/e2eHarness.ts                |  55 ++++-
 src/renderer/stores/dockStore.rules.test.ts   | 100 +++++++++
 src/renderer/stores/dockStore.test.ts         |  32 +--
 src/renderer/stores/dockStore.ts              |  46 ++--
 14 files changed, 530 insertions(+), 55 deletions(-)
 create mode 100644 docs/dock-rules.md
 create mode 100644 e2e/dock-rules.spec.ts
 create mode 100644 src/renderer/stores/dockStore.rules.test.ts

diff --git a/docs/dock-rules.md b/docs/dock-rules.md
new file mode 100644
index 00000000..0b85b202
--- /dev/null
+++ b/docs/dock-rules.md
@@ -0,0 +1,55 @@
+# Dock behavior and test matrix
+
+This document defines the supported dock state transitions. “Maximize” means a
+reversible presentation: a main-dock split is merged into tabs, or one pane of a
+canvas node is promoted beside its containing canvas. “Minimize” means restoring
+that saved layout. A presentation is restorable only while both its destination
+and, for a promoted canvas pane, its source topology remain unchanged.
+
+## Drag and placement rules
+
+| Source | Drop target | Result | Automated coverage |
+|---|---|---|---|
+| Dock tab | Same stack tab bar | Reorder tabs; a one-tab self-drop is a no-op | `dockStore.rules.test.ts`, `drag/resolve.test.ts`, `drag/commit.test.ts` |
+| Dock tab | Another dock stack tab bar | Move into that stack as a tab | `dockStore.presentation.test.ts`, `drag/commit.test.ts` |
+| Dock tab | Left/right dock edge | Horizontal split, before/after the target | `dockStore.rules.test.ts`, `three-way-split.spec.ts` |
+| Dock tab | Top/bottom dock edge | Vertical split, before/after the target | `dockStore.rules.test.ts`, `drag/commit.test.ts` |
+| Dock tab | Empty canvas | Create a canvas node containing the panel | `dock-rules.spec.ts` |
+| Dock tab | Canvas-node tab bar | Add the panel as a tab and remove it from the main dock | `drag/commit.test.ts` |
+| Dock tab | Canvas-node edge | Add the panel as a split pane and remove it from the main dock | `drag/commit.test.ts` |
+| Canvas node/pane | Empty area of the same canvas | Reposition the node; preserve its tabs/splits | `drag-move.spec.ts`, `drag-split.spec.ts` |
+| Canvas node/pane | Another canvas-node tab bar | Merge into the target as tabs; remove an emptied source node | `drag-split.spec.ts` |
+| Canvas node/pane | Another canvas-node edge | Split the target; remove an emptied source node | `drag-split.spec.ts` |
+| Canvas node/pane | Main-dock tab bar | Move into the dock as a tab | `dock-rules.spec.ts` |
+| Canvas node/pane | Main-dock edge | Move into the dock as a split | `drag/commit.test.ts` |
+| Canvas node/pane | Outside the application window | Detach into a new dock window | `drag-detach.spec.ts` |
+| Canvas panel | A canvas node | Reject recursive canvas nesting | `drag-canvas-into-canvas.spec.ts` |
+| Detached-window panel | Main dock or canvas | Commit only after receiver acknowledgement; otherwise recover in the detached session | `detached-panels.spec.ts`, `existing-window-drop.test.ts`, `windowPanelSync.test.ts` |
+
+For every split edge, placement order is fixed: left/top inserts before the
+target and right/bottom inserts after it. Same-direction splits gain an equal
+sibling instead of creating an unnecessary nested split.
+
+## Split, maximize, minimize, and invalidation rules
+
+| Starting state | Action | Defined result | Restore status | Automated coverage |
+|---|---|---|---|---|
+| One dock stack | Split right | A new surface in a horizontal sibling | Not applicable | `three-way-split.spec.ts`, `dock-rules.spec.ts` |
+| Main dock with any split tree | Maximize a leaf | Flatten the zone into one tab stack, keeping deterministic tree order and the selected leaf active | Valid | `dockStore.presentation.test.ts`, `dock-rules.spec.ts` |
+| Maximized main dock | Select a merged tab | Only active selection changes | Remains valid | `dockStore.rules.test.ts` |
+| Maximized main dock | Resize/toggle another zone, add a panel to another zone, or take a snapshot | Presented topology is unchanged | Remains valid | `dockStore.rules.test.ts` |
+| Maximized main dock | Add/remove/reorder/move a presented tab, split/collapse its stack, or restore a snapshot | Keep the user’s new topology | Permanently invalidated | `dockStore.rules.test.ts`, `dock-rules.spec.ts` |
+| Maximized main dock, unchanged | Minimize | Restore the exact pre-merge split tree | Consumed | `dockStore.presentation.test.ts`, `dock-rules.spec.ts` |
+| Singleton canvas node | Maximize | Remove the empty node and promote its panel beside the canvas | Valid | `CanvasNode.groupDrag.test.tsx` |
+| Tabbed or split canvas node | Maximize one pane | Promote only the active pane; preserve the remaining node | Valid | `CanvasNode.groupDrag.test.tsx`, `dock-rules.spec.ts` |
+| Promoted canvas pane | Select canvas/promoted tab, resize surrounding split, resize/toggle an unrelated zone, add to another zone, or take a snapshot | No structural change to either saved topology | Remains valid | `dockStore.presentation.test.ts` |
+| Promoted canvas pane | Structurally change the source canvas node | Keep both the promoted pane and the edited source | Permanently invalidated | `CanvasNode.groupDrag.test.tsx`, `dock-rules.spec.ts` |
+| Promoted canvas pane | Add/remove/reorder/move/split/collapse in the destination, including moving away and back | Keep the user’s new destination | Permanently invalidated | `dockStore.presentation.test.ts`, `dock-rules.spec.ts` |
+| Promoted canvas pane, both sides unchanged | Minimize | Restore the exact node id, position, size, tabs, split tree, and active pane | Consumed | `CanvasNode.groupDrag.test.tsx`, `dock-rules.spec.ts` |
+| Any active presentation | Maximize another stack/pane | Ignore the second request; presentations never nest | Existing presentation remains valid | `dockStore.presentation.test.ts` |
+| Invalidated presentation | Minimize | No-op; the restore control is removed | Unavailable | `dockStore.presentation.test.ts`, `dock-rules.spec.ts` |
+
+The invalidation rule is intentionally structural. Tab selection and split
+ratios are presentation details and are safe; panel identity, order, tree shape,
+and source-node existence are ownership/topology and cannot be overwritten by a
+later restore.
diff --git a/e2e/detached-panels.spec.ts b/e2e/detached-panels.spec.ts
index ded79c31..91d9f11d 100644
--- a/e2e/detached-panels.spec.ts
+++ b/e2e/detached-panels.spec.ts
@@ -136,6 +136,7 @@ test('screenshot preview and comment editing stay in the detached canvas window'
   await expect.poll(() => calloutGroup.getAttribute('transform')).not.toBe(initialTransform)
   await detached.getByRole('button', { name: 'Save' }).click()
   await expect(detached.getByRole('dialog', { name: 'Screenshot preview' })).toHaveCount(0)
+  await expect(detached.getByLabel('Annotated screenshot')).toBeVisible()
   await expect.poll(() => app.evaluate(() => (globalThis as typeof globalThis & { __detachedAnnotation?: string }).__detachedAnnotation?.startsWith('data:image/png;base64,'))).toBe(true)
 })
 
diff --git a/e2e/dock-rules.spec.ts b/e2e/dock-rules.spec.ts
new file mode 100644
index 00000000..cb1d89e2
--- /dev/null
+++ b/e2e/dock-rules.spec.ts
@@ -0,0 +1,200 @@
+import { expect, test, type Locator } from '@playwright/test'
+import type { ElectronApplication, Page } from 'playwright'
+import {
+  closeApp,
+  dragMouse,
+  getNodeRect,
+  launchApp,
+  resetViewport,
+  seedTerminal,
+  setZoom,
+  titleBarCentre,
+} from './fixtures/electron-app'
+
+let app: ElectronApplication
+let page: Page
+let canvasId: string
+
+test.beforeEach(async () => {
+  ;({ electronApp: app, mainWindow: page } = await launchApp())
+  const window = await app.browserWindow(page)
+  await window.evaluate((browserWindow) => browserWindow.setContentSize(1400, 850))
+  await page.evaluate(() => window.__cateE2E!.setSidebarHidden(true))
+  canvasId = await page.evaluate(() => window.__cateE2E!.activeCanvasPanelId()!)
+})
+
+test.afterEach(async () => {
+  if (app) await closeApp(app)
+})
+
+function stackFor(panelId: string): Locator {
+  return page.locator('[data-dock-stack-id]').filter({
+    has: page.locator(`[data-tab-panel-id="${panelId}"]`),
+  })
+}
+
+async function dragTabTo(panelId: string, point: { x: number; y: number }): Promise<void> {
+  const box = await page.locator(`[data-tab-panel-id="${panelId}"]`).boundingBox()
+  if (!box) throw new Error(`Panel tab ${panelId} is not visible`)
+  await dragMouse(
+    page,
+    { x: box.x + box.width / 2, y: box.y + box.height / 2 },
+    point,
+    { steps: 30, pauseAtEnd: 100 },
+  )
+}
+
+async function splitCanvasNode(): Promise<{
+  nodeId: string
+  panelIds: string[]
+}> {
+  await setZoom(page, 0.65)
+  await resetViewport(page)
+  const source = await seedTerminal(page, { x: 300, y: 100 })
+  const target = await seedTerminal(page, { x: 1000, y: 100 })
+  const sourceGrab = await titleBarCentre(page, source)
+  const targetRect = await getNodeRect(page, target)
+  if (!sourceGrab || !targetRect) throw new Error('Canvas fixture did not render')
+  await dragMouse(
+    page,
+    sourceGrab,
+    { x: targetRect.x + 12, y: targetRect.y + targetRect.height / 2 },
+    { steps: 30, pauseAtEnd: 100 },
+  )
+  await expect(page.locator(`[data-node-id="${source}"]`)).toHaveCount(0)
+  await expect.poll(async () => {
+    return page.evaluate((id) => window.__cateE2E!.canvasDebug().find((node) => node.id === id)?.leafCount, target)
+  }).toBe(2)
+  const panelIds = await page.evaluate((id) => {
+    return window.__cateE2E!.canvasDebug().find((node) => node.id === id)!.panelIds
+  }, target)
+  return { nodeId: target, panelIds }
+}
+
+async function promoteFirstPane(nodeId: string): Promise<void> {
+  const node = page.locator(`[data-node-id="${nodeId}"]`)
+  const overlay = node.locator('[data-unfocused-overlay]')
+  if (await overlay.count()) await overlay.click({ position: { x: 5, y: 5 } })
+  await node.getByRole('button', { name: 'Move panel into dock' }).first().click()
+}
+
+test('main-dock split can be maximized, restored, and permanently invalidated by a new split', async () => {
+  await page.evaluate(() => window.__cateE2E!.clearCanvas())
+  const first = await page.evaluate(() => window.__cateE2E!.createPanel('surface'))
+  await stackFor(first).getByRole('button', { name: 'Split Right', exact: true }).click()
+  await expect.poll(() => page.evaluate(() => window.__cateE2E!.dockDebug().zones.center.leafCount)).toBe(2)
+
+  await page.getByRole('button', { name: 'Merge splits into tabs' }).first().click()
+  await expect.poll(() => page.evaluate(() => window.__cateE2E!.dockDebug())).toMatchObject({
+    zones: { center: { leafCount: 1 } },
+    presentation: { canRestore: true },
+  })
+
+  await page.getByRole('button', { name: 'Restore previous layout' }).click()
+  await expect.poll(() => page.evaluate(() => window.__cateE2E!.dockDebug())).toMatchObject({
+    zones: { center: { leafCount: 2 } },
+    presentation: null,
+  })
+
+  await page.getByRole('button', { name: 'Merge splits into tabs' }).first().click()
+  await page.getByRole('button', { name: 'Split Right', exact: true }).click()
+  await expect.poll(() => page.evaluate(() => window.__cateE2E!.dockDebug())).toMatchObject({
+    zones: { center: { leafCount: 2 } },
+    presentation: null,
+  })
+  await expect(page.getByRole('button', { name: 'Restore previous layout' })).toHaveCount(0)
+})
+
+test('a panel can move from the dock into the canvas and back into the dock', async () => {
+  const panelId = await page.evaluate(() => window.__cateE2E!.createPanel('surface'))
+  await page.locator(`[data-tab-panel-id="${canvasId}"]`).click()
+  const canvas = await page.locator(`[data-canvas-panel-id="${canvasId}"]`).boundingBox()
+  if (!canvas) throw new Error('Canvas is not visible')
+  await dragTabTo(panelId, { x: canvas.x + canvas.width * 0.72, y: canvas.y + canvas.height * 0.7 })
+
+  await expect.poll(() => page.evaluate((id) => {
+    const e2e = window.__cateE2E!
+    return {
+      docked: e2e.dockDebug().zones.center.panelIds.includes(id),
+      canvas: e2e.canvasDebug().some((node) => node.panelIds.includes(id)),
+    }
+  }, panelId)).toEqual({ docked: false, canvas: true })
+
+  const nodeId = await page.evaluate((id) => {
+    return window.__cateE2E!.canvasDebug().find((node) => node.panelIds.includes(id))!.id
+  }, panelId)
+  const grab = await titleBarCentre(page, nodeId)
+  const canvasTab = await page.locator(`[data-tab-panel-id="${canvasId}"]`).boundingBox()
+  if (!grab || !canvasTab) throw new Error('Dock round-trip fixture is not visible')
+  await dragMouse(
+    page,
+    grab,
+    { x: canvasTab.x + canvasTab.width / 2, y: canvasTab.y + canvasTab.height / 2 },
+    { steps: 30, pauseAtEnd: 100 },
+  )
+
+  await expect.poll(() => page.evaluate((id) => {
+    const e2e = window.__cateE2E!
+    return {
+      docked: e2e.dockDebug().zones.center.panelIds.includes(id),
+      canvas: e2e.canvasDebug().some((node) => node.panelIds.includes(id)),
+    }
+  }, panelId)).toEqual({ docked: true, canvas: false })
+})
+
+test('a split canvas node promotes one pane and restores the exact mini-dock', async () => {
+  const fixture = await splitCanvasNode()
+  await promoteFirstPane(fixture.nodeId)
+
+  await expect.poll(() => page.evaluate(() => {
+    return window.__cateE2E!.dockDebug().presentation?.panelId ?? null
+  })).not.toBeNull()
+  const promotedId = await page.evaluate(() => window.__cateE2E!.dockDebug().presentation!.panelId!)
+  expect(fixture.panelIds).toContain(promotedId)
+  await expect.poll(() => page.evaluate(({ canvasId, nodeId }) => {
+    return window.__cateE2E!.canvasDebug(canvasId).find((node) => node.id === nodeId)
+  }, { canvasId, nodeId: fixture.nodeId })).toMatchObject({ leafCount: 1 })
+
+  await page.getByRole('button', { name: 'Restore previous layout' }).click()
+  await expect.poll(() => page.evaluate((id) => {
+    return window.__cateE2E!.canvasDebug().find((node) => node.id === id)
+  }, fixture.nodeId)).toMatchObject({ panelIds: fixture.panelIds, leafCount: 2 })
+  await expect.poll(() => page.evaluate(() => window.__cateE2E!.dockDebug().presentation)).toBeNull()
+})
+
+test('editing the source canvas after promotion invalidates restore', async () => {
+  const fixture = await splitCanvasNode()
+  await promoteFirstPane(fixture.nodeId)
+  await expect.poll(() => page.evaluate(() => window.__cateE2E!.dockDebug().presentation?.canRestore)).toBe(true)
+
+  await page.locator(`[data-tab-panel-id="${canvasId}"]`).click()
+  const node = page.locator(`[data-node-id="${fixture.nodeId}"]`)
+  await node.getByRole('button', { name: 'New Tab' }).click()
+  await page.getByRole('menu', { name: 'New Tab' }).getByRole('menuitem', { name: 'Files' }).click()
+
+  await expect.poll(() => page.evaluate(() => window.__cateE2E!.dockDebug().presentation)).toBeNull()
+  await expect(page.getByRole('button', { name: 'Restore previous layout' })).toHaveCount(0)
+})
+
+test('dragging a promoted pane back into the canvas invalidates restore', async () => {
+  const fixture = await splitCanvasNode()
+  await promoteFirstPane(fixture.nodeId)
+  await expect.poll(() => page.evaluate(() => {
+    return window.__cateE2E!.dockDebug().presentation?.panelId ?? null
+  })).not.toBeNull()
+  const promotedId = await page.evaluate(() => window.__cateE2E!.dockDebug().presentation!.panelId!)
+
+  await page.locator(`[data-tab-panel-id="${canvasId}"]`).click()
+  const canvas = await page.locator(`[data-canvas-panel-id="${canvasId}"]`).boundingBox()
+  if (!canvas) throw new Error('Canvas is not visible')
+  await dragTabTo(promotedId, { x: canvas.x + canvas.width * 0.78, y: canvas.y + canvas.height * 0.72 })
+
+  await expect.poll(() => page.evaluate((id) => {
+    const e2e = window.__cateE2E!
+    return {
+      presentation: e2e.dockDebug().presentation,
+      inCanvas: e2e.canvasDebug().some((node) => node.panelIds.includes(id)),
+    }
+  }, promotedId)).toEqual({ presentation: null, inCanvas: true })
+  await expect(page.getByRole('button', { name: 'Restore previous layout' })).toHaveCount(0)
+})
diff --git a/e2e/drag-canvas-into-canvas.spec.ts b/e2e/drag-canvas-into-canvas.spec.ts
index 75f2dc2c..38ac918e 100644
--- a/e2e/drag-canvas-into-canvas.spec.ts
+++ b/e2e/drag-canvas-into-canvas.spec.ts
@@ -3,7 +3,6 @@ import {
   launchApp,
   closeApp,
   seedTerminal,
-  seedCanvasPanel,
   resetViewport,
   titleBarCentre,
   getNodeRect,
@@ -16,6 +15,8 @@ let page: Page
 
 test.beforeEach(async () => {
   ;({ electronApp: app, mainWindow: page } = await launchApp())
+  const window = await app.browserWindow(page)
+  await window.evaluate((browserWindow) => browserWindow.setContentSize(1600, 900))
   // Collapse the left sidebar. It's a real flex item that PUSHES the canvas now
   // (#295), stealing ~260px of width — enough that a node seeded at canvas x=700
   // has its centre fall off the right window edge, so a drop aimed there misses
@@ -26,34 +27,32 @@ test.beforeEach(async () => {
 test.afterEach(async () => closeApp(app))
 
 test('canvas panel cannot be docked into a canvas-node mini-dock', async () => {
-  // Set up: a terminal node (the would-be drop target) and a canvas-typed node
-  // (the would-be source). Canvas-in-canvas is forbidden.
-  const target = await seedTerminal(page, { x: 700, y: 200 })
-  const source = await seedCanvasPanel(page, { x: 200, y: 200 })
-  // The canvas panel may have landed inside a sub-canvas or as a workspace
-  // panel — if it didn't appear as a canvas-node, skip with a clear note.
-  const sourceEl = await page.$(`[data-node-id="${source}"]`)
-  test.skip(!sourceEl, 'createCanvasPanel did not produce a canvas-node in the active canvas')
+  const canvasId = await page.evaluate(() => window.__cateE2E!.activeCanvasPanelId()!)
+  const target = await seedTerminal(page, { x: 1000, y: 200 })
+  const source = await page.evaluate(() => window.__cateE2E!.createPanel('canvas'))
+  await page.locator(`[data-tab-panel-id="${canvasId}"]`).click()
 
-  const grab = await titleBarCentre(page, source)
+  const sourceTab = await page.locator(`[data-tab-panel-id="${source}"]`).boundingBox()
   const tRect = await getNodeRect(page, target)
+  if (!sourceTab || !tRect) throw new Error('Canvas rejection fixture is not visible')
   // Aim at the target's tab-bar (would be 'tab' drop for a non-canvas source).
   const dropPoint = { x: tRect!.x + tRect!.width / 2, y: tRect!.y + 10 }
-  await dragMouse(page, grab!, dropPoint, { steps: 20, pauseAtEnd: 50 })
-  await page.waitForTimeout(150)
+  await dragMouse(page, {
+    x: sourceTab.x + sourceTab.width / 2,
+    y: sourceTab.y + sourceTab.height / 2,
+  }, dropPoint, { steps: 20, pauseAtEnd: 50 })
 
-  // Canvas source must NOT have been absorbed into target's stack.
-  // It may have moved (canvas-add elsewhere) or stayed put — but it MUST still
-  // exist as a canvas-node somewhere.
-  const sourceStill = await page.$(`[data-node-id="${source}"]`)
-  expect(sourceStill).not.toBeNull()
+  await expect.poll(() => page.evaluate((id) => ({
+    docked: window.__cateE2E!.dockDebug().zones.center.panelIds.includes(id),
+    nested: window.__cateE2E!.canvasDebug().some((node) => node.panelIds.includes(id)),
+  }), source)).toEqual({ docked: true, nested: false })
 })
 
 test('non-canvas tab is accepted into a canvas-node mini-dock', async () => {
   // Regression guard: the rejection above must be specific to canvas — a
   // terminal tab still docks normally.
-  const target = await seedTerminal(page, { x: 700, y: 200 })
-  const source = await seedTerminal(page, { x: 200, y: 200 })
+  const target = await seedTerminal(page, { x: 1000, y: 200 })
+  const source = await seedTerminal(page, { x: 300, y: 200 })
   const grab = await titleBarCentre(page, source)
   const tRect = await getNodeRect(page, target)
   const dropPoint = { x: tRect!.x + tRect!.width / 2, y: tRect!.y + 10 }
diff --git a/e2e/drag-move.spec.ts b/e2e/drag-move.spec.ts
index 20072c23..f221cb2a 100644
--- a/e2e/drag-move.spec.ts
+++ b/e2e/drag-move.spec.ts
@@ -104,12 +104,14 @@ test('source node is hidden while dragging', async () => {
   await page.mouse.move(grab!.x, grab!.y)
   await page.mouse.down()
   await page.mouse.move(grab!.x + 100, grab!.y + 80, { steps: 10 })
-  await page.waitForTimeout(250) // wait for opacity transition (150ms) + slop
-  const opacity = await page.evaluate(
-    (id) => getComputedStyle(document.querySelector(`[data-node-id="${id}"]`)!).opacity,
+  const style = await page.evaluate(
+    (id) => {
+      const computed = getComputedStyle(document.querySelector(`[data-node-id="${id}"]`)!)
+      return { visibility: computed.visibility, pointerEvents: computed.pointerEvents }
+    },
     nodeId,
   )
-  expect(parseFloat(opacity)).toBe(0)
+  expect(style).toEqual({ visibility: 'hidden', pointerEvents: 'none' })
   await page.mouse.up()
 })
 
diff --git a/e2e/drag-split.spec.ts b/e2e/drag-split.spec.ts
index 87b927ce..03966315 100644
--- a/e2e/drag-split.spec.ts
+++ b/e2e/drag-split.spec.ts
@@ -16,6 +16,8 @@ let page: Page
 
 test.beforeEach(async () => {
   ;({ electronApp: app, mainWindow: page } = await launchApp())
+  const window = await app.browserWindow(page)
+  await window.evaluate((browserWindow) => browserWindow.setContentSize(1600, 900))
   // Collapse the left sidebar. It's now a real flex item that PUSHES the canvas
   // (it used to overlay it), stealing ~260px of canvas width. With it open, a
   // node seeded at canvas x=1000 renders off the right window edge, so edge-drops
diff --git a/e2e/fixtures/electron-app.ts b/e2e/fixtures/electron-app.ts
index 6baa8379..bbfa5c13 100644
--- a/e2e/fixtures/electron-app.ts
+++ b/e2e/fixtures/electron-app.ts
@@ -184,6 +184,26 @@ export async function seedTerminal(
   return nodeId
 }
 
+export async function seedEditor(
+  page: Page,
+  point: { x: number; y: number } = { x: 200, y: 200 },
+): Promise<string> {
+  const hint = await page.evaluate((p) => window.__cateE2E!.createEditor(p), point)
+  const nodeId = await page
+    .waitForFunction(
+      (h) => {
+        const n = window.__cateE2E!.nodes().find((x) => x.id === h || x.panelId === h)
+        return n ? n.id : null
+      },
+      hint,
+      { timeout: 15_000 },
+    )
+    .then((handle) => handle.jsonValue() as Promise<string>)
+  await page.waitForSelector(`[data-node-id="${nodeId}"]`)
+  await page.waitForTimeout(100)
+  return nodeId
+}
+
 export async function seedCanvasPanel(
   page: Page,
   point: { x: number; y: number } = { x: 200, y: 200 },
diff --git a/src/renderer/canvas/RecentScreenshotButton.test.tsx b/src/renderer/canvas/RecentScreenshotButton.test.tsx
index be4e631e..6b0d2fd9 100644
--- a/src/renderer/canvas/RecentScreenshotButton.test.tsx
+++ b/src/renderer/canvas/RecentScreenshotButton.test.tsx
@@ -74,6 +74,29 @@ it('does not crash the canvas when an older preload lacks screenshot APIs', asyn
   }
 })
 
+it('renders the annotation marker for a saved screenshot', async () => {
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  const originalAPI = window.electronAPI
+  window.electronAPI = {
+    ...originalAPI,
+    getRecentScreenshot: vi.fn().mockResolvedValue([{
+      id: 'annotated', filePath: '/annotated.png', dataUrl: 'data:image/png;base64,test', annotated: true,
+    }]),
+    onRecentScreenshotChanged: vi.fn(() => () => {}),
+    dragRecentScreenshot: vi.fn().mockResolvedValue(undefined),
+  }
+  const host = document.createElement('div')
+  const root = createRoot(host)
+  try {
+    await act(async () => root.render(<RecentScreenshotButton />))
+    expect(host.querySelector('[aria-label="Annotated screenshot"]')).not.toBeNull()
+  } finally {
+    act(() => root.unmount())
+    window.electronAPI = originalAPI
+    vi.unstubAllGlobals()
+  }
+})
+
 it('opens clicked screenshots, navigates with overlay controls and keys, and closes the viewer', async () => {
   vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
   const originalAPI = window.electronAPI
diff --git a/src/renderer/canvas/RecentScreenshotButton.tsx b/src/renderer/canvas/RecentScreenshotButton.tsx
index eeb79afa..eab7f61b 100644
--- a/src/renderer/canvas/RecentScreenshotButton.tsx
+++ b/src/renderer/canvas/RecentScreenshotButton.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
-import { CaretLeft, CaretRight, DownloadSimple, Minus, Plus, X } from '@phosphor-icons/react'
+import { CaretLeft, CaretRight, DownloadSimple, Minus, PencilSimple, Plus, X } from '@phosphor-icons/react'
 import type { RecentScreenshot } from '../../shared/recentScreenshot'
 import { Tooltip } from '../ui/Tooltip'
 import { createPortal } from 'react-dom'
diff --git a/src/renderer/canvas/ScreenshotDrawing.tsx b/src/renderer/canvas/ScreenshotDrawing.tsx
index e246e8cf..971b70e3 100644
--- a/src/renderer/canvas/ScreenshotDrawing.tsx
+++ b/src/renderer/canvas/ScreenshotDrawing.tsx
@@ -190,7 +190,7 @@ export function ScreenshotDrawing({ id, url, width, height, toolbarHost, onClose
         return <g key={callout.id} transform={`rotate(${callout.rotation} ${center.x} ${center.y})`}>
           <foreignObject x={callout.x} y={callout.y} width={callout.width} height={callout.height}
             onClick={event => event.stopPropagation()}>
-          <div className="group relative h-full w-full overflow-hidden rounded-2xl bg-black/30 text-white shadow-xl backdrop-blur-sm" xmlns="http://www.w3.org/1999/xhtml">
+          <div className="group relative h-full w-full overflow-hidden rounded-2xl bg-black/30 text-white shadow-xl backdrop-blur-sm">
             <button type="button" aria-label={`Move comment ${index + 1}`} title="Drag comment"
               className="absolute left-1.5 top-1/2 z-10 -translate-y-1/2 cursor-grab rounded-full p-1 text-white/65 hover:bg-white/15 hover:text-white active:cursor-grabbing"
               onClick={event => event.stopPropagation()}
diff --git a/src/renderer/lib/e2eHarness.ts b/src/renderer/lib/e2eHarness.ts
index df89e05c..80f60bb5 100644
--- a/src/renderer/lib/e2eHarness.ts
+++ b/src/renderer/lib/e2eHarness.ts
@@ -21,8 +21,9 @@ import { getLastReveal } from './editor/editorReveal'
 import { applyTheme } from './themeManager'
 import { BUILT_IN_THEMES } from '../../shared/themes'
 import { terminalRegistry } from './terminal/terminalRegistry'
-import type { Point, WorktreeMeta } from '../../shared/types'
-import { activeDockPanelId } from '../../shared/collectPanelIds'
+import type { DockLayoutNode, DockZonePosition, Point, WorktreeMeta } from '../../shared/types'
+import { activeDockPanelId, collectPanelIds } from '../../shared/collectPanelIds'
+import { getOrCreateWorkspaceDockStore } from './workspace/dockRegistry'
 import { useSettingsStore } from '../stores/settingsStore'
 import { parseCodingAgentId, type CodingAgentRunSnapshot } from '../../shared/codingAgentRuns'
 import { codingAgentSnapshot, handleCodingAgentMethod } from './agent/codingAgentDriver'
@@ -76,6 +77,11 @@ declare global {
       ): Promise<BrowserOutcome>
       browserWebContentsId(panelId: string): number | null
       nodes(): { id: string; panelId: string; origin: Point; size: { width: number; height: number } }[]
+      dockDebug(): {
+        zones: Record<DockZonePosition, { panelIds: string[]; leafCount: number }>
+        presentation: { stackId: string; panelId: string | null; canRestore: boolean } | null
+      }
+      canvasDebug(canvasPanelId?: string): { id: string; panelIds: string[]; leafCount: number }[]
       zoom(): number
       setZoom(z: number): void
       resetViewport(): void
@@ -282,6 +288,49 @@ export function installE2EHarness(): void {
     }))
   }
 
+  const leafCount = (layout: DockLayoutNode | null): number => {
+    if (!layout) return 0
+    return layout.type === 'tabs'
+      ? 1
+      : layout.children.reduce((total, child) => total + leafCount(child), 0)
+  }
+
+  const dockDebug = () => {
+    const workspaceId = useAppStore.getState().selectedWorkspaceId
+    const state = getOrCreateWorkspaceDockStore(workspaceId).getState()
+    const zone = (position: DockZonePosition) => ({
+      panelIds: collectPanelIds(state.zones[position].layout),
+      leafCount: leafCount(state.zones[position].layout),
+    })
+    return {
+      zones: {
+        left: zone('left'),
+        right: zone('right'),
+        bottom: zone('bottom'),
+        center: zone('center'),
+      },
+      presentation: state.presentation
+        ? {
+            stackId: state.presentation.stackId,
+            panelId: state.presentation.panelId ?? null,
+            canRestore: state.canRestorePresentation(state.presentation.stackId),
+          }
+        : null,
+    }
+  }
+
+  const canvasDebug = (canvasPanelId?: string) => {
+    const store = canvasPanelId
+      ? getOrCreateCanvasStoreForPanel(canvasPanelId)
+      : activeCanvasStore()
+    if (!store) return []
+    return Object.values(store.getState().nodes).map((node) => ({
+      id: node.id,
+      panelIds: collectPanelIds(node.dockLayout),
+      leafCount: leafCount(node.dockLayout),
+    }))
+  }
+
   const zoom = () => activeCanvasStore()?.getState().zoomLevel ?? 1
 
   const setZoom = (z: number) => {
@@ -548,6 +597,8 @@ export function installE2EHarness(): void {
     browserInvoke,
     browserWebContentsId,
     nodes,
+    dockDebug,
+    canvasDebug,
     zoom,
     setZoom,
     resetViewport,
diff --git a/src/renderer/stores/dockStore.rules.test.ts b/src/renderer/stores/dockStore.rules.test.ts
new file mode 100644
index 00000000..5e96f8ff
--- /dev/null
+++ b/src/renderer/stores/dockStore.rules.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest'
+import type { DockLayoutNode } from '../../shared/types'
+import { createDockStore } from './dockStore'
+
+type PlacementTarget =
+  | { type: 'tab' }
+  | { type: 'split'; edge: 'left' | 'right' | 'top' | 'bottom' }
+
+function layoutAfter(target: PlacementTarget): DockLayoutNode {
+  const store = createDockStore()
+  store.getState().dockPanel('a', 'center')
+  const first = store.getState().getPanelLocation('a')
+  if (first?.type !== 'dock') throw new Error('Expected dock location')
+  const dropTarget = target.type === 'tab'
+    ? { type: 'tab' as const, stackId: first.stackId }
+    : { ...target, stackId: first.stackId }
+  store.getState().dockPanel('b', 'center', dropTarget)
+  const layout = store.getState().zones.center.layout
+  if (!layout) throw new Error('Expected dock layout')
+  return layout
+}
+
+const placements: Array<{
+  label: string
+  target: PlacementTarget
+  direction?: 'horizontal' | 'vertical'
+  panelOrder: string[]
+}> = [
+  { label: 'tab', target: { type: 'tab' }, panelOrder: ['a', 'b'] },
+  { label: 'left split', target: { type: 'split', edge: 'left' }, direction: 'horizontal', panelOrder: ['b', 'a'] },
+  { label: 'right split', target: { type: 'split', edge: 'right' }, direction: 'horizontal', panelOrder: ['a', 'b'] },
+  { label: 'top split', target: { type: 'split', edge: 'top' }, direction: 'vertical', panelOrder: ['b', 'a'] },
+  { label: 'bottom split', target: { type: 'split', edge: 'bottom' }, direction: 'vertical', panelOrder: ['a', 'b'] },
+]
+
+function panelOrder(layout: DockLayoutNode): string[] {
+  return layout.type === 'tabs'
+    ? layout.panelIds
+    : layout.children.flatMap(panelOrder)
+}
+
+describe('dock placement rule matrix', () => {
+  it.each(placements)('$label has deterministic direction and ordering', ({ target, direction, panelOrder: order }) => {
+    const layout = layoutAfter(target)
+    expect(layout.type).toBe(direction ? 'split' : 'tabs')
+    if (layout.type === 'split') expect(layout.direction).toBe(direction)
+    expect(panelOrder(layout)).toEqual(order)
+  })
+})
+
+function mergedFixture() {
+  const store = createDockStore()
+  store.getState().dockPanel('a', 'center')
+  const first = store.getState().getPanelLocation('a')
+  if (first?.type !== 'dock') throw new Error('Expected dock location')
+  store.getState().dockPanel('b', 'center', { type: 'split', stackId: first.stackId, edge: 'right' })
+  store.getState().mergeSplitToStack(first.stackId)
+  return { store, stackId: first.stackId }
+}
+
+const safeAfterMerge: Array<[string, (fixture: ReturnType<typeof mergedFixture>) => void]> = [
+  ['selecting another merged tab', ({ store, stackId }) => store.getState().setActiveTab(stackId, 1)],
+  ['resizing an unrelated zone', ({ store }) => store.getState().setZoneSize('right', 420)],
+  ['toggling an unrelated zone', ({ store }) => store.getState().toggleZone('right')],
+  ['adding a panel to another zone', ({ store }) => store.getState().dockPanel('unrelated', 'right')],
+  ['taking a persistence snapshot', ({ store }) => { store.getState().getSnapshot() }],
+]
+
+const invalidAfterMerge: Array<[string, (fixture: ReturnType<typeof mergedFixture>) => void]> = [
+  ['adding an active tab', ({ store, stackId }) => {
+    store.getState().dockPanel('new', 'center', { type: 'tab', stackId })
+  }],
+  ['adding a background tab', ({ store, stackId }) => {
+    store.getState().dockPanel('new', 'center', { type: 'tab', stackId }, false)
+  }],
+  ['removing the first tab', ({ store }) => store.getState().undockPanel('a')],
+  ['removing the second tab', ({ store }) => store.getState().undockPanel('b')],
+  ['reordering tabs', ({ store, stackId }) => store.getState().moveTab('b', stackId, stackId, 0)],
+  ['moving a tab to another zone', ({ store }) => store.getState().dockPanel('b', 'right')],
+  ['splitting the merged stack', ({ store, stackId }) => {
+    store.getState().dockPanel('new', 'center', { type: 'split', stackId, edge: 'right' })
+  }],
+  ['collapsing the merged stack', ({ store, stackId }) => store.getState().collapseStack(stackId)],
+  ['restoring a snapshot', ({ store }) => store.getState().restoreSnapshot(store.getState().getSnapshot())],
+]
+
+describe('merged dock presentation rule matrix', () => {
+  it.each(safeAfterMerge)('remains restorable after %s', (_label, action) => {
+    const fixture = mergedFixture()
+    action(fixture)
+    expect(fixture.store.getState().canRestorePresentation(fixture.stackId)).toBe(true)
+  })
+
+  it.each(invalidAfterMerge)('is permanently invalidated by %s', (_label, action) => {
+    const fixture = mergedFixture()
+    action(fixture)
+    expect(fixture.store.getState().presentation).toBeNull()
+    expect(fixture.store.getState().restorePresentation(fixture.stackId)).toBe(false)
+  })
+})
diff --git a/src/renderer/stores/dockStore.test.ts b/src/renderer/stores/dockStore.test.ts
index c223004d..924458f3 100644
--- a/src/renderer/stores/dockStore.test.ts
+++ b/src/renderer/stores/dockStore.test.ts
@@ -462,6 +462,17 @@ describe('moveTab', () => {
     expect(rootStack(store, 'bottom').panelIds).toEqual(['b', 'c', 'a'])
     expectTreeInvariants(store.getState().zones)
   })
+
+  it('keeps a single tab when asked to move it within its own stack', () => {
+    const store = createDockStore()
+    store.getState().dockPanel('a', 'bottom')
+    const stack = rootStack(store, 'bottom')
+
+    store.getState().moveTab('a', stack.id, stack.id, 0)
+
+    expect(rootStack(store, 'bottom').panelIds).toEqual(['a'])
+    expectTreeInvariants(store.getState().zones)
+  })
 })
 
 describe('setActiveTab', () => {
@@ -657,27 +668,19 @@ describe('cross-zone moves', () => {
   })
 })
 
-// Each test below asserts the DESIRED behavior and is marked `.fails` because
-// the current implementation silently loses or corrupts state instead. When the
-// underlying hole is fixed, the test starts passing and vitest flags it —
-// remove the `.fails` marker then.
-describe('known holes (documented as expected failures)', () => {
-  it.fails('dockPanel into a different zone must not duplicate the panel across zones', () => {
+describe('invalid and stale dock targets', () => {
+  it('dockPanel into a different zone does not duplicate the panel across zones', () => {
     const store = createDockStore()
     store.getState().dockPanel('a', 'left')
 
-    // The duplicate guard in dockPanel only cleans the TARGET zone's tree.
-    // Docking a panel that lives in another zone leaves it in both. Today the
-    // drag commit always undocks first, but any caller that skips that (or a
-    // refactor that reorders it) corrupts the layout silently.
     store.getState().dockPanel('a', 'bottom')
 
-    expectTreeInvariants(store.getState().zones) // 'a' appears twice today
+    expectTreeInvariants(store.getState().zones)
     expect(store.getState().getPanelLocation('a')).toMatchObject({ zone: 'bottom' })
     expect(collectStacks(zoneLayout(store, 'left')).some((s) => s.panelIds.includes('a'))).toBe(false)
   })
 
-  it.fails('a split target whose stack is gone falls back to zone append instead of dropping the panel', () => {
+  it('a split target whose stack is gone falls back to zone append instead of dropping the panel', () => {
     const store = createDockStore()
     store.getState().dockPanel('a', 'bottom')
 
@@ -688,7 +691,7 @@ describe('known holes (documented as expected failures)', () => {
     expect(store.getState().getPanelLocation('b')).toBeDefined()
   })
 
-  it.fails('moveTab to a stack that no longer exists does not lose the panel', () => {
+  it('moveTab to a stack that no longer exists does not lose the panel', () => {
     const store = createDockStore()
     store.getState().dockPanel('a', 'bottom')
     store.getState().dockPanel('b', 'bottom')
@@ -699,7 +702,7 @@ describe('known holes (documented as expected failures)', () => {
     expect(store.getState().getPanelLocation('a')).toBeDefined()
   })
 
-  it.fails('a tab insert index beyond the stack length keeps activeIndex in range', () => {
+  it('a tab insert index beyond the stack length keeps activeIndex in range', () => {
     const store = createDockStore()
     store.getState().dockPanel('a', 'bottom')
     const stack = rootStack(store, 'bottom')
@@ -744,6 +747,7 @@ describe('end-to-end rearrangement scenario', () => {
 
     // Left zone emptied by the move; bottom holds everything, each panel locatable.
     expect(zoneLayout(store, 'left')).toBeNull()
+    expect(s().zones.left.visible).toBe(false)
     for (const id of ['term1', 'agent', 'term2', 'files']) {
       const loc = s().getPanelLocation(id)
       expect(loc?.type).toBe('dock')
diff --git a/src/renderer/stores/dockStore.ts b/src/renderer/stores/dockStore.ts
index aa4e0267..892fe942 100644
--- a/src/renderer/stores/dockStore.ts
+++ b/src/renderer/stores/dockStore.ts
@@ -20,6 +20,7 @@ import {
   findTabStack,
   findZoneForStack,
   findStackContainingPanelAcrossZones,
+  findTabStackAcrossZones,
   findFirstTabStack,
 } from './dockTreeUtils'
 import { clearActivePanelIfMatches } from '../lib/activePanel'
@@ -339,13 +340,23 @@ export function createDockStore(initialState?: DockStateSnapshot) {
 
   dockPanel(panelId, zone, target, activate = true) {
     set((state) => {
-      const zoneState = state.zones[zone]
-      let newLayout = zoneState.layout
-
-      // Guard: remove panel from target zone layout first to prevent duplicates
-      if (newLayout) {
-        newLayout = removePanelFromTree(newLayout, panelId)
+      // A panel has exactly one dock owner. Remove any existing occurrence
+      // before placing it, even when the caller skips an explicit undock.
+      const zones = { ...state.zones }
+      for (const position of ALL_ZONES) {
+        const current = zones[position]
+        if (!current.layout) continue
+        const layout = removePanelFromTree(current.layout, panelId)
+        if (layout !== current.layout) {
+          zones[position] = {
+            ...current,
+            layout,
+            visible: position === 'center' ? true : (layout !== null ? current.visible : false),
+          }
+        }
       }
+      const zoneState = zones[zone]
+      let newLayout = zoneState.layout
 
       // A 'tab' target whose stack no longer exists (e.g. it was closed since the
       // user last interacted with it) falls through to the default zone-append
@@ -354,7 +365,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
         // Add to existing tab stack
         const stack = findTabStack(newLayout, target.stackId)!
         {
-          const insertIndex = target.index ?? stack.panelIds.length
+          const insertIndex = Math.max(0, Math.min(target.index ?? stack.panelIds.length, stack.panelIds.length))
           const newPanelIds = [...stack.panelIds]
           newPanelIds.splice(insertIndex, 0, panelId)
           const updatedStack: DockTabStack = {
@@ -366,7 +377,11 @@ export function createDockStore(initialState?: DockStateSnapshot) {
             ? replaceInTree(newLayout, stack.id, updatedStack)
             : updatedStack
         }
-      } else if (target?.type === 'split' && target.stackId) {
+      } else if (
+        target?.type === 'split'
+        && target.stackId
+        && findTabStack(newLayout, target.stackId)
+      ) {
         // Split an existing stack
         const newStack: DockTabStack = {
           type: 'tabs',
@@ -431,10 +446,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
         }
       }
 
-      const zones = {
-        ...state.zones,
-        [zone]: { ...zoneState, visible: activate ? true : zoneState.visible, layout: newLayout },
-      }
+      zones[zone] = { ...zoneState, visible: activate ? true : zoneState.visible, layout: newLayout }
       return { zones, presentation: state.presentation }
     })
   },
@@ -469,6 +481,10 @@ export function createDockStore(initialState?: DockStateSnapshot) {
 
   moveTab(panelId, fromStackId, toStackId, index) {
     set((state) => {
+      const source = findTabStackAcrossZones(state.zones, fromStackId)
+      const target = findTabStackAcrossZones(state.zones, toStackId)
+      if (!source?.panelIds.includes(panelId) || !target) return state
+      if (fromStackId === toStackId && source.panelIds.length === 1) return state
       const zones = { ...state.zones }
 
       // Find and update source and target stacks across all zones
@@ -481,9 +497,11 @@ export function createDockStore(initialState?: DockStateSnapshot) {
         if (fromStack) {
           const newPanelIds = fromStack.panelIds.filter((id) => id !== panelId)
           if (newPanelIds.length === 0) {
+            const layout = removePanelFromTree(zoneState.layout, panelId)
             zones[pos] = {
               ...zoneState,
-              layout: removePanelFromTree(zoneState.layout, panelId),
+              layout,
+              visible: pos === 'center' ? true : (layout !== null ? zoneState.visible : false),
             }
           } else {
             const updated: DockTabStack = {
@@ -501,7 +519,7 @@ export function createDockStore(initialState?: DockStateSnapshot) {
         // Add to target
         const toStack = findTabStack(zones[pos].layout, toStackId)
         if (toStack) {
-          const insertIndex = index ?? toStack.panelIds.length
+          const insertIndex = Math.max(0, Math.min(index ?? toStack.panelIds.length, toStack.panelIds.length))
           const newPanelIds = [...toStack.panelIds]
           newPanelIds.splice(insertIndex, 0, panelId)
           const updated: DockTabStack = {

From 403184dbd6790e26306355ce368f1f563c129d61 Mon Sep 17 00:00:00 2001
From: Anton <antonhorn@icloud.com>
Date: Fri, 11 Sep 2026 11:53:03 +0200
Subject: [PATCH 7/7] Make screenshot path test cross-platform

---
 src/main/ipc/recentScreenshot.test.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/main/ipc/recentScreenshot.test.ts b/src/main/ipc/recentScreenshot.test.ts
index 67ea7465..04193e97 100644
--- a/src/main/ipc/recentScreenshot.test.ts
+++ b/src/main/ipc/recentScreenshot.test.ts
@@ -140,7 +140,8 @@ describe('recent macOS screenshot', () => {
     mocks.decode.mockReturnValue({ isEmpty: () => false, toPNG: () => png })
     const saved = await invoke(RECENT_SCREENSHOT_SAVE, shot.id, 'data:image/png;base64,test')
     expect(saved.annotated).toBe(true)
-    expect(saved.filePath).toMatch(/^\/desktop\/shot-annotated-.*\.png$/)
+    expect(path.dirname(saved.filePath)).toBe(path.dirname(path.normalize('/desktop/shot.png')))
+    expect(path.basename(saved.filePath)).toMatch(/^shot-annotated-.*\.png$/)
     expect(mocks.writeFile).toHaveBeenCalledWith(saved.filePath, png, { flag: 'wx' })
     expect(mocks.runtimeGrant).toHaveBeenCalledWith(saved.filePath, 1)
     expect(mocks.runtimeGrant).toHaveBeenCalledWith(saved.filePath, 2)