Skip to content

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.

fix(terminal): explain macOS screenshot paste routes

reviewfe213c8d4a58
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 reserves
Ctrl+Shift+C for the inspector and a page cannot `preventDefault()` it — which is where Server
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
+ **Text paste uses the platform event** (`isPasteShortcut` → the `'native'` action): ⌘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
@@ -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 the
terminal's BOTTOM-RIGHT corner (`.term-copy-pill`, the same class on the canvas node and the
kanban card modal — one session seen twice must not speak in two voices; bottom-right because
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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.md
index 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 only
diff --git a/src/renderer/components/ShortcutsPanel.test.tsx b/src/renderer/components/ShortcutsPanel.test.tsx
index 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 = true
let root: Root | null = null
@@ -212,6 +239,7 @@ describe('ShortcutsPanel (DOM)', () => {
root = null
document.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.tsx
index 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: string
rows: ShortcutRow[]
+ note?: string
}
export interface ShortcutSectionsOptions {
@@ -183,6 +184,20 @@ export function buildShortcutSections(o: ShortcutSectionsOptions): ShortcutSecti
if (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.css
index 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);
}