Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(windows): let Ctrl+V paste in terminals
enes397c09db0ef6
diff --git a/CLAUDE.md b/CLAUDE.mdindex 588ebeaec..bda1d5e82 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -788,7 +788,16 @@ session.layouts still copy. A copy chord is **always swallowed**, selection or not: letting Ctrl+Shift+Cfall through would reach the pty as `\x03` (SIGINT). Ctrl+Insert exists because Chromium reservesCtrl+Shift+C for the inspector and a page cannot `preventDefault()` it — which is where Server- Edition users land. Plain **Ctrl+C** is never intercepted. To select in **xterm** instead of tmux+ Edition users land. Plain **Ctrl+C** is never intercepted.+ **PASTE is the platform's, never ours** (`isPasteShortcut` → the `'native'` action): we own no+ paste path — ⌘V on mac reaches the Edit menu's `{role:'paste'}`, whose `paste` event xterm frames+ as a bracketed paste. All the terminal does is stop CANCELLING the chord, and that is a+ **Windows-only** claim: xterm's keymap turns Ctrl+V into `\x16` with `cancel`, which suppressed+ Chromium's paste command *and* the Ctrl+V accelerator behind it, so Ctrl+V pasted nothing at all+ there (issue #562). Off Windows the chord stays `\x16` on purpose — mac pastes with ⌘V, Linux+ with Ctrl+Shift+V, and Ctrl+V is a key vim/readline users really send. Ctrl+Shift+V and+ Shift+Insert need no branch: measured against `evaluateKeyboardEvent`, xterm produces neither a+ key nor a cancel for them, so the platform already pastes. To select in **xterm** instead of tmux(or inside an app that grabs the mouse, like vim/htop), hold **Option** (mac —xterm's `macOptionClickForcesSelection`) or **Shift** (Linux/Windows) while dragging.**Copying now says so**: the OSC 52 handler floats a transient `Copied N lines` pill over thediff --git a/src/renderer/components/kanban/ModalTerminal.tsx b/src/renderer/components/kanban/ModalTerminal.tsxindex 0326c8fa4..8a25e1a1f 100644--- a/src/renderer/components/kanban/ModalTerminal.tsx+++ b/src/renderer/components/kanban/ModalTerminal.tsx@@ -247,8 +247,9 @@ export function ModalTerminal({ nodeId, spawn, searchOpen, onCloseSearch }: Modaconst action = terminalKeyAction(e, term.hasSelection(), ownsProjectJump, registryOwns)if (action === 'pass') return true// 'bubble': hand the chord to the window dispatcher — no preventDefault (it bails on- // defaultPrevented), no xterm processing. See TerminalNode's twin comment.- if (action === 'bubble') return false+ // defaultPrevented), no xterm processing. 'native' leaves the event uncancelled for the+ // PLATFORM's own paste (Windows Ctrl+V). See TerminalNode's twin comment.+ if (action === 'bubble' || action === 'native') return falsee.preventDefault()if (action === 'copy') window.nodeTerminal.clipboard.writeText(term.getSelection())else if (action === 'shift-enter' && sessionId) transport.write(sessionId, SHIFT_ENTER_SEQ)diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex 3349b4228..4fe4e151c 100644--- a/src/renderer/nodes/TerminalNode.tsx+++ b/src/renderer/nodes/TerminalNode.tsx@@ -2690,7 +2690,12 @@ export function TerminalNode({// into a CSI write and cancel the event — and DO NOT preventDefault: the dispatcher bails// on defaultPrevented events, so a prevented bubble would kill the very dispatch this// exists to reach.- if (action === 'bubble') return false+ // 'native': same mechanics, different owner — the PLATFORM's paste (Windows Ctrl+V, issue+ // #562). xterm would map it to \x16 and cancel the keydown, which suppresses both+ // Chromium's paste command and the Edit menu's Ctrl+V accelerator; leaving the event+ // untouched lets the ordinary `paste` event reach xterm's textarea, exactly as ⌘V does on+ // macOS (bracketed-paste framing included).+ if (action === 'bubble' || action === 'native') return falsee.preventDefault()if (action === 'copy') window.nodeTerminal.clipboard.writeText(term.getSelection())// Shift+Enter → ESC+CR so agent CLIs insert a newline instead of submittingdiff --git a/src/renderer/terminal/terminal-config.test.ts b/src/renderer/terminal/terminal-config.test.tsindex bf103c9a6..e7ac95768 100644--- a/src/renderer/terminal/terminal-config.test.ts+++ b/src/renderer/terminal/terminal-config.test.ts@@ -8,6 +8,7 @@ import {disposalAction,forgetNodeTermState,isCopyShortcut,+ isPasteShortcut,isLetterboxed,letterboxFor,markRecycled,@@ -494,6 +495,36 @@ describe('copyKeyAction', () => {})})+describe('isPasteShortcut (issue #562 — Ctrl+V did nothing on Windows)', () => {+ const v = (p: Partial<CopyShortcutEvent> = {}): CopyShortcutEvent =>+ ev({ key: 'v', code: 'KeyV', ...p })++ it('claims Ctrl+V on Windows', () => {+ expect(isPasteShortcut(v({ ctrlKey: true }), true)).toBe(true)+ // Non-Latin layout: the physical KeyV position still counts, like isCopyShortcut's KeyC.+ expect(isPasteShortcut(ev({ key: 'м', code: 'KeyV', ctrlKey: true }), true)).toBe(true)+ })++ it('claims NOTHING off Windows — there Ctrl+V is a pty control byte and paste is Cmd+V / Ctrl+Shift+V', () => {+ // vim's blockwise-visual and readline's literal-next live on this chord.+ expect(isPasteShortcut(v({ ctrlKey: true }), false)).toBe(false)+ })++ it('leaves the chords xterm already passes through alone', () => {+ // Measured in @xterm/xterm's evaluateKeyboardEvent: Ctrl+Shift+V and Shift+Insert produce+ // neither a key nor a cancel, so the platform paste already runs for them.+ expect(isPasteShortcut(v({ ctrlKey: true, shiftKey: true }), true)).toBe(false)+ expect(isPasteShortcut(ev({ key: 'Insert', code: 'Insert', shiftKey: true }), true)).toBe(false)+ })++ it('ignores keyup, plain V, AltGr (ctrl+alt) and Cmd+V', () => {+ expect(isPasteShortcut(v({ ctrlKey: true, type: 'keyup' }), true)).toBe(false)+ expect(isPasteShortcut(v(), true)).toBe(false)+ expect(isPasteShortcut(v({ ctrlKey: true, altKey: true }), true)).toBe(false)+ expect(isPasteShortcut(v({ metaKey: true }), true)).toBe(false)+ })+})+describe('terminalKeyAction', () => {it('maps Shift+Enter keydown to shift-enter', () => {expect(terminalKeyAction(ev({ key: 'Enter', code: 'Enter', shiftKey: true }), false)).toBe(@@ -570,6 +601,38 @@ describe('terminalKeyAction', () => {expect(SHIFT_ENTER_SEQ).toBe('\x1b\r')})+ // Issue #562: xterm maps Ctrl+V to \x16 AND cancels the keydown, which suppresses both+ // Chromium's paste command and the Edit menu's Ctrl+V accelerator — so nothing pasted at all.+ // 'native' = return false from the xterm handler WITHOUT preventDefault, so the platform pastes.+ it('hands Windows Ctrl+V to the platform paste', () => {+ const ctrlV = ev({ key: 'v', code: 'KeyV', ctrlKey: true })+ expect(terminalKeyAction(ctrlV, false, false, false, true)).toBe('native')+ expect(terminalKeyAction(ctrlV, true, false, false, true)).toBe('native')+ })++ it('leaves Ctrl+V as a pty control byte off Windows', () => {+ const ctrlV = ev({ key: 'v', code: 'KeyV', ctrlKey: true })+ expect(terminalKeyAction(ctrlV, false, false, false, false)).toBe('pass')+ // The default reads the live platform; under vitest's node env that is not Windows, so every+ // existing call site keeps its byte-identical behavior.+ expect(terminalKeyAction(ctrlV, false)).toBe('pass')+ })++ it('never lets the paste claim shadow a copy chord or Shift+Enter', () => {+ expect(terminalKeyAction(ev({ ctrlKey: true, shiftKey: true }), true, false, false, true)).toBe(+ 'copy'+ )+ expect(+ terminalKeyAction(+ ev({ key: 'Enter', code: 'Enter', shiftKey: true }),+ false,+ false,+ false,+ true+ )+ ).toBe('shift-enter')+ })+// The jump-to-project chord: WHICH events are the chord is decided once, in lib/projectJump.ts// (and tested there — layout, AltGr, keyup, digit range). This module only obeys the answer.// It bubbles (not swallow) so the window dispatcher can perform the switch while stilldiff --git a/src/renderer/terminal/terminal-config.ts b/src/renderer/terminal/terminal-config.tsindex 7e4c61a47..c83efca18 100644--- a/src/renderer/terminal/terminal-config.ts+++ b/src/renderer/terminal/terminal-config.ts@@ -6,6 +6,7 @@ import type {TerminalCursorInactiveStyle,TerminalCursorStyle} from '@shared/types'+import { isWindowsPlatform } from '@shared/platform-utils'import { isKnownTerminalThemeId, resolveTerminalTheme } from './themes'/**@@ -745,6 +746,37 @@ export function isCopyShortcut(e: CopyShortcutEvent): boolean {return cmdC || ctrlShiftC}+/**+ * The paste chord that xterm's own keymap would EAT — Ctrl+V, and only on Windows.+ *+ * We do not paste ourselves: the platform already does, and identically on every surface. On+ * macOS ⌘V reaches the Edit menu's `{role:'paste'}` (Chromium routes those into the focused+ * element), which dispatches a `paste` event to xterm's helper textarea; xterm's handler applies+ * bracketed-paste framing and writes it to the pty. All this decision does is stop xterm from+ * CANCELLING the keydown, so the same platform path runs on Windows too.+ *+ * Measured against `@xterm/xterm`'s `evaluateKeyboardEvent` (issue #562):+ * - **Ctrl+V** maps to `\x16` (SYN) with `cancel: true`, so xterm calls `preventDefault()` — which+ * suppresses Chromium's paste editing command AND keeps the Ctrl+V menu accelerator from firing+ * (an accelerator only runs on a keydown the renderer did not consume). Hence: nothing pasted,+ * nothing typed, no error. This is the whole bug.+ * - **Ctrl+Shift+V** and **Shift+Insert** produce no key and no cancel, so xterm already lets them+ * through to the platform. They need no branch here, and adding one would only risk breaking+ * what works.+ *+ * **Windows only, deliberately.** On macOS ⌘V is the paste chord and Ctrl+V must stay `\x16`; on+ * Linux the terminal convention is Ctrl+Shift+V, and Ctrl+V is a key people actually send (vim's+ * blockwise-visual, readline's literal-next). Windows Terminal's own default is Ctrl+V = paste,+ * so this matches what a Windows user's other terminal does — at the cost of `\x16` there, the+ * same trade Windows Terminal ships.+ */+export function isPasteShortcut(e: CopyShortcutEvent, isWindows: boolean): boolean {+ if (!isWindows || e.type !== 'keydown') return false+ if (e.key.toLowerCase() !== 'v' && e.code !== 'KeyV') return false+ // AltGr reports ctrl+alt, and Ctrl+Shift+V is not ours to claim (xterm already passes it).+ return e.ctrlKey && !e.shiftKey && !e.altKey && !e.metaKey+}+/*** What a terminal keydown that MIGHT be a copy chord should do:* - `copy` — it is a copy chord and there is a selection: copy it, swallow the key.@@ -771,7 +803,7 @@ export function copyKeyAction(e: CopyShortcutEvent, hasSelection: boolean): Copy*/export const SHIFT_ENTER_SEQ = '\x1b\r'-export type TerminalKeyAction = CopyKeyAction | 'shift-enter' | 'bubble'+export type TerminalKeyAction = CopyKeyAction | 'shift-enter' | 'bubble' | 'native'/*** Superset of `copyKeyAction` used by the terminal's custom key handler.@@ -794,7 +826,8 @@ export function terminalKeyAction(e: CopyShortcutEvent,hasSelection: boolean,ownsProjectJump = false,- registryOwns = false+ registryOwns = false,+ isWindows: boolean = isWindowsPlatform()): TerminalKeyAction {if (e.type === 'keydown' &&@@ -814,6 +847,13 @@ export function terminalKeyAction(if (ownsProjectJump) return 'bubble'const base = copyKeyAction(e, hasSelection)if (base !== 'pass') return base+ // Windows Ctrl+V: hand the chord to the PLATFORM's own paste (see `isPasteShortcut`). 'native'+ // has the same mechanics as 'bubble' — return false from the xterm handler, do NOT+ // preventDefault — but a different reason, so the two are not one branch: 'bubble' means the+ // window dispatcher owns a registry command, 'native' means Chromium's editing command (and the+ // Edit menu's `{role:'paste'}` accelerator behind it) does. Both need the event left uncancelled;+ // only 'bubble' implies a registry owner.+ if (isPasteShortcut(e, isWindows)) return 'native'// `registryOwns` — decided by the caller via `terminalChordBubbles`, the same live-registry// matcher discipline as `ownsProjectJump` — means the window dispatcher will claim this chord// (an allowInTerminal app/canvas command). 'bubble' tells the consumer to return false WITHOUTdiff --git a/src/renderer/terminal/terminal-key-handler-parity.test.ts b/src/renderer/terminal/terminal-key-handler-parity.test.tsnew file mode 100644index 000000000..484785fa3--- /dev/null+++ b/src/renderer/terminal/terminal-key-handler-parity.test.ts@@ -0,0 +1,37 @@+import { readFileSync } from 'fs'+import { join } from 'path'+import { describe, expect, it } from 'vitest'++/**+ * TWO xterm key handlers, one decision function.+ *+ * `TerminalNode` (canvas) and `ModalTerminal` (kanban card modal) both call `terminalKeyAction`+ * and both act on its answer — the modal's own comments call itself a MIRROR of the node's. The+ * decision is shared and tested; the ACTING is duplicated, and that is where it drifts.+ *+ * The uncancelled actions are the fragile half: `bubble` and `native` must return `false` WITHOUT+ * `preventDefault()`, and a call site that knows only `bubble` falls through to the `preventDefault`+ * line — which for `native` is precisely issue #562's bug (Ctrl+V eaten, nothing pasted), except+ * now on one surface only, and the shared unit tests would still be green.+ *+ * Source-level, in the spirit of `hook-verified-parity.test.ts`: the alternative is a full+ * xterm+DOM harness, and vitest here runs in the node environment.+ */+const FILES = [+ 'src/renderer/nodes/TerminalNode.tsx',+ 'src/renderer/components/kanban/ModalTerminal.tsx'+]++describe('terminal key-handler parity', () => {+ for (const rel of FILES) {+ it(`${rel} returns without preventDefault for both uncancelled actions`, () => {+ const src = readFileSync(join(process.cwd(), rel), 'utf8')+ expect(src).toContain("action === 'bubble' || action === 'native'")+ // …and it does so BEFORE the preventDefault that copy / shift-enter need.+ const guard = src.indexOf("action === 'bubble' || action === 'native'")+ const prevent = src.indexOf('e.preventDefault()', guard)+ expect(guard).toBeGreaterThan(-1)+ expect(prevent).toBeGreaterThan(guard)+ })+ }+})