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(terminal): explain macOS screenshot paste routes
reviewfe213c8d4a58
diff --git a/CLAUDE.md b/CLAUDE.mdindex f108819c7..d92da891a 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1173,8 +1173,8 @@ session.fall 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 ServerEdition 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+ **Text paste uses the platform event** (`isPasteShortcut` → the `'native'` action): ⌘V on+ mac reaches the Edit menu's `{role:'paste'}`, whose `paste` event xterm framesas 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 suppressedChromium's paste command *and* the Ctrl+V accelerator behind it, so Ctrl+V pasted nothing at all@@ -1184,6 +1184,13 @@ session.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.+ **Screenshot paste (#712):** the capture handler in both TerminalNode and ModalTerminal+ owns files/images: save/upload, then paste the path, suppressing accompanying text. A+ macOS Ctrl+V may instead let a local foreground agent read its own system clipboard.+ Configured agent identity proves neither foreground state nor clipboard support, and a+ PTY write has no image receipt. Never synthesize that key or fall back between routes.+ The macOS shortcuts reference explains both keys; its Server Edition copy explicitly+ says Ctrl+V cannot transfer the viewer's clipboard to the host. SSH keeps remote uploads.**Copying now says so**: the OSC 52 handler floats a transient `Copied N lines` pill over theterminal's BOTTOM-RIGHT corner (`.term-copy-pill`, the same class on the canvas node and thekanban card modal — one session seen twice must not speak in two voices; bottom-right becausediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 0223794bd..79c98aaff 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -613,6 +613,12 @@ feature from the one they asked for.## Testing+**Screenshot paste has one route per gesture.** On macOS, Cmd+V saves/uploads a file and+pastes its path; Ctrl+V belongs to the foreground program. A node's configured agent is not+proof of foreground clipboard-image support. Keep shell/SSH/Server file routing and capture+suppression of accompanying text; do not synthesize Ctrl+V or try both routes without a+capability and receipt protocol. The shortcuts panel documents this distinction (#712).+`npm test` must pass, and `npm run typecheck` is the fastest gate.Beyond that, one habit is worth more than any other here:diff --git a/README.md b/README.mdindex 943db5b43..9d1dc01f5 100644--- a/README.md+++ b/README.md@@ -292,6 +292,16 @@ These are the defaults — every one of them is remappable in **Settings → Key| `⌘,` | Settings · `⌘/` Shortcuts || `Right-click` | Actions menu (empty space or node) |+**Pasting screenshots on macOS:** in a terminal, **Cmd+V** saves the image and pastes its+file path. **Ctrl+V** sends a control key to the foreground program. A local agent with+clipboard-image support, such as Claude Code, may attach the image directly at its input+prompt; shells and editors give that key other meanings. nodeterm does not detect this+capability or retry with the other route. Use Cmd+V for SSH sessions: the image is uploaded+and its remote path is pasted. In Server Edition, image paste uploads to the terminal host+and depends on browser clipboard access; Ctrl+V does not transfer the browser's clipboard+to the host. This distinction also appears in **Keyboard shortcuts → Pasting screenshots+on macOS** and applies to both canvas and kanban terminals.+## 🏗 Architecture- **Electron, three contexts** — `src/main` (the Electron shell), `src/preload` (the onlydiff --git a/src/renderer/components/ShortcutsPanel.test.tsx b/src/renderer/components/ShortcutsPanel.test.tsxindex cf99327de..bf61d237c 100644--- a/src/renderer/components/ShortcutsPanel.test.tsx+++ b/src/renderer/components/ShortcutsPanel.test.tsx@@ -203,6 +203,33 @@ describe('buildShortcutSections — platform and non-command rows', () => {})})+describe('macOS screenshot paste discoverability', () => {+ it('distinguishes file paste from a foreground control key without promising agent support', () => {+ const sections = build(() => [])+ expect(rowFor(sections, 'Save the image and paste its file path')).toEqual(['⌘', 'V'])+ expect(rowFor(sections, 'Send a control key to the foreground program')).toEqual(['Ctrl', 'V'])+ const note = sections.find((s) => s.title === 'Pasting screenshots on macOS')?.note+ expect(note).toContain('only at that agent’s input prompt')+ expect(note).toContain('For SSH sessions, use Cmd+V')+ expect(note).toContain('does not detect image support or retry')+ })++ it('never advertises a local clipboard attachment from a Server browser', () => {+ const note = build(() => [], { browser: true })+ .find((s) => s.title === 'Pasting screenshots on macOS')?.note+ expect(note).toContain('Ctrl+V does not transfer your browser clipboard')+ expect(note).toContain('browser clipboard access')+ expect(note).not.toContain('may attach an image')+ })++ it('does not teach the macOS Ctrl+V behavior on other platforms', () => {+ for (const browser of [true, false]) {+ expect(rowFor(build(() => [], { isMac: false, browser }),+ 'Send a control key to the foreground program')).toBeUndefined()+ }+ })+})+describe('ShortcutsPanel (DOM)', () => {;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = truelet root: Root | null = null@@ -212,6 +239,7 @@ describe('ShortcutsPanel (DOM)', () => {root = nulldocument.body.innerHTML = ''useSettings.setState({ settings: { ...DEFAULT_SETTINGS } })+ vi.restoreAllMocks()})const render = (props: Partial<Parameters<typeof ShortcutsPanel>[0]> = {}): void => {@@ -224,6 +252,15 @@ describe('ShortcutsPanel (DOM)', () => {const rowLabels = (): string[] =>[...document.querySelectorAll('.shortcut-label')].map((n) => n.textContent ?? '')+ it('renders the screenshot explanation alongside both keys on macOS', () => {+ vi.spyOn(navigator, 'platform', 'get').mockReturnValue('MacIntel')+ render()+ expect(rowLabels()).toContain('Save the image and paste its file path')+ expect(rowLabels()).toContain('Send a control key to the foreground program')+ expect(document.querySelector('.shortcuts__note')?.textContent)+ .toContain('only at that agent’s input prompt')+ })+it('reads the live override map through the settings store', () => {useSettings.setState({settings: { ...DEFAULT_SETTINGS, keybindings: { 'canvas.tidy': [] } as never }diff --git a/src/renderer/components/ShortcutsPanel.tsx b/src/renderer/components/ShortcutsPanel.tsxindex ae5e34bf4..f3c5605b8 100644--- a/src/renderer/components/ShortcutsPanel.tsx+++ b/src/renderer/components/ShortcutsPanel.tsx@@ -66,6 +66,7 @@ export interface ShortcutRow {export interface ShortcutSection {title: stringrows: ShortcutRow[]+ note?: string}export interface ShortcutSectionsOptions {@@ -183,6 +184,20 @@ export function buildShortcutSections(o: ShortcutSectionsOptions): ShortcutSectiif (rows.length) sections.push({ title: group, rows })}sections.push({ title: 'Terminal behavior', rows: behaviorRows(o) })+ // These are platform/program keys, not remappable nodeterm commands. A configured agent+ // cannot prove the foreground program reads images from this viewer's clipboard (#712).+ if (o.isMac) {+ sections.push({+ title: 'Pasting screenshots on macOS',+ rows: [+ row(['⌘', 'V'], 'Save the image and paste its file path'),+ row(['Ctrl', 'V'], 'Send a control key to the foreground program')+ ],+ note: o.browser+ ? 'In Server Edition, the image is uploaded to the terminal host. Ctrl+V does not transfer your browser clipboard to that host. Image paste depends on browser clipboard access.'+ : 'A local agent that supports clipboard images (such as Claude Code) may attach an image with Ctrl+V. Use it only at that agent’s input prompt; shells and editors give this key other meanings. For SSH sessions, use Cmd+V to upload the image and paste its remote path. nodeterm does not detect image support or retry with the other route.'+ })+ }return sections}@@ -247,6 +262,7 @@ export function ShortcutsPanel({ onClose, onCustomize }: ShortcutsPanelProps) {</span></div>))}+ {s.note && <p className="shortcuts__note">{s.note}</p>}</section>))}</div>diff --git a/src/renderer/styles.css b/src/renderer/styles.cssindex caec75eb2..80359ee6c 100644--- a/src/renderer/styles.css+++ b/src/renderer/styles.css@@ -6048,6 +6048,13 @@ body,font-size: 13px;}+.shortcuts__note {+ margin: 8px 0 0;+ font-size: 12px;+ line-height: 1.5;+ color: var(--muted);+}+.shortcut-label {color: var(--text);}