fix(cli): add Option+V for clipboard image paste on macOS (#8120)

* fix(cli): add Option+V for clipboard image paste on macOS (#8118)

macOS terminals intercept Cmd+V for text paste, so the existing
Cmd+V binding for clipboard image paste never fires. Users had to
discover Ctrl+V through trial and error.

Changes:
- keyBindings.ts: add { key: 'v', meta: true } (Option/Alt+V) to
  PASTE_CLIPBOARD_IMAGE bindings on non-Windows platforms
- KeyboardShortcuts.tsx: update macOS hint from 'cmd+v' to
  'ctrl+v / opt+v' to reflect what actually works

* fix(cli): correct macOS image-paste shortcut hint (#8118)

* test(cli): cover platform-specific image-paste shortcut hint (#8118)

* fix(cli): make option+v image paste work on stock macOS terminals (#8118)

* fix(cli): address review feedback on macOS image-paste shortcut (#8118)

- Guard the option-composed glyph lookup with Object.hasOwn so inherited Object.prototype members can never resolve as a composed key.

- Add a non-macOS pass-through test for the "√" glyph, mirroring the existing "†" coverage.

- Correct the keyboard-shortcuts docs: Ctrl+V also pastes on macOS, matching the overlay hint.

---------

Co-authored-by: qwen-code-dev-bot <qwen-code-dev-bot@users.noreply.github.com>
Co-authored-by: Shaojin Wen <shaojin.wensj@alibaba-inc.com>

Author: qwen-code-dev-bot

docs/users/reference/keyboard-shortcuts.md

@@ -45,7 +45,7 @@ This document lists the available keyboard shortcuts in Qwen Code.
 | `Ctrl+Y`                                              | Retry the last failed request.                                                                                                      |
 | `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F`    | Move the cursor one word to the right.                                                                                              |
 | `Ctrl+U`                                              | Delete from the cursor to the beginning of the line.                                                                                |
-| `Ctrl+V` (Windows: `Alt+V`)                           | Paste clipboard content. If the clipboard contains an image, it will be saved and a reference to it will be inserted in the prompt. |
+| `Ctrl+V` / `Option+V` (Windows: `Alt+V`)              | Paste clipboard content. If the clipboard contains an image, it will be saved and a reference to it will be inserted in the prompt. |
 | `Ctrl+W` / `Meta+Backspace` / `Ctrl+Backspace`        | Delete the word to the left of the cursor.                                                                                          |
 | `Ctrl+X`                                              | Open the current input in an external editor.                                                                                       |
 

packages/cli/src/ui/components/KeyboardShortcuts.test.tsx

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render } from 'ink-testing-library';
+import { KeyboardShortcuts } from './KeyboardShortcuts.js';
+
+// A narrow width forces the single-column layout so each shortcut renders on
+// its own line. ink-testing-library hard-codes stdout to 100 columns, so a
+// multi-column layout chosen from a wider mock can still wrap physically and
+// break these assertions for reasons unrelated to the hint text.
+vi.mock('../hooks/useTerminalSize.js', () => ({
+  useTerminalSize: vi.fn(() => ({ columns: 40, rows: 24 })),
+}));
+
+const originalPlatform = process.platform;
+
+function stubPlatform(platform: NodeJS.Platform): void {
+  Object.defineProperty(process, 'platform', {
+    value: platform,
+    configurable: true,
+  });
+}
+
+describe('KeyboardShortcuts', () => {
+  afterEach(() => {
+    stubPlatform(originalPlatform);
+  });
+
+  it.each([
+    ['darwin', 'ctrl+v / option+v to paste images', ['alt+v']],
+    ['win32', 'alt+v to paste images', ['option+v']],
+    ['linux', 'ctrl+v to paste images', ['option+v', 'alt+v']],
+  ] as const)(
+    'advertises the %s image-paste key',
+    (platform, expectedPasteCell, absentKeys) => {
+      stubPlatform(platform);
+      const { lastFrame } = render(<KeyboardShortcuts />);
+      const frame = lastFrame() ?? '';
+      expect(frame).toContain(expectedPasteCell);
+      for (const absent of absentKeys) {
+        expect(frame).not.toContain(absent);
+      }
+    },
+  );
+});

packages/cli/src/ui/components/KeyboardShortcuts.tsx

@@ -20,7 +20,9 @@ const getNewlineKey = () =>
   process.platform === 'win32' ? 'ctrl+enter' : 'ctrl+j';
 const getPasteKey = () => {
   if (process.platform === 'win32') return 'alt+v';
-  return process.platform === 'darwin' ? 'cmd+v' : 'ctrl+v';
+  // macOS terminals (iTerm2, Terminal.app) intercept Cmd+V for text paste, so
+  // advertise Ctrl+V and Option+V, which reach the CLI as image-paste keys.
+  return process.platform === 'darwin' ? 'ctrl+v / option+v' : 'ctrl+v';
 };
 const getExternalEditorKey = () =>
   process.platform === 'darwin' ? 'ctrl+x' : 'ctrl+x';

packages/cli/src/ui/contexts/KeypressContext.test.tsx

@@ -219,6 +219,96 @@ describe('KeypressContext - Kitty Protocol', () => {
       }
     });
 
+    it('rewrites macOS composed Option+v glyph "√" to Alt+v', () => {
+      const originalPlatform = process.platform;
+      Object.defineProperty(process, 'platform', {
+        value: 'darwin',
+        configurable: true,
+        writable: true,
+      });
+      try {
+        const keyHandler = vi.fn();
+
+        const { result } = renderHook(() => useKeypressContext(), {
+          wrapper,
+        });
+
+        act(() => {
+          result.current.subscribe(keyHandler);
+        });
+
+        act(() => {
+          stdin.pressKey({
+            name: '',
+            ctrl: false,
+            meta: false,
+            shift: false,
+            paste: false,
+            sequence: '√',
+          });
+        });
+
+        expect(keyHandler).toHaveBeenCalledWith(
+          expect.objectContaining({
+            name: 'v',
+            meta: true,
+            sequence: '√',
+          }),
+        );
+      } finally {
+        Object.defineProperty(process, 'platform', {
+          value: originalPlatform,
+          configurable: true,
+          writable: true,
+        });
+      }
+    });
+
+    it('leaves "√" untouched on non-macOS platforms', () => {
+      const originalPlatform = process.platform;
+      Object.defineProperty(process, 'platform', {
+        value: 'linux',
+        configurable: true,
+        writable: true,
+      });
+      try {
+        const keyHandler = vi.fn();
+
+        const { result } = renderHook(() => useKeypressContext(), {
+          wrapper,
+        });
+
+        act(() => {
+          result.current.subscribe(keyHandler);
+        });
+
+        act(() => {
+          stdin.pressKey({
+            name: '',
+            ctrl: false,
+            meta: false,
+            shift: false,
+            paste: false,
+            sequence: '√',
+          });
+        });
+
+        expect(keyHandler).toHaveBeenCalledWith(
+          expect.objectContaining({
+            name: '',
+            meta: false,
+            sequence: '√',
+          }),
+        );
+      } finally {
+        Object.defineProperty(process, 'platform', {
+          value: originalPlatform,
+          configurable: true,
+          writable: true,
+        });
+      }
+    });
+
     it('should recognize regular enter key (keycode 13) in kitty protocol', async () => {
       const keyHandler = vi.fn();
 

packages/cli/src/ui/contexts/KeypressContext.tsx

@@ -50,14 +50,18 @@ import { FOCUS_IN, FOCUS_OUT } from '../hooks/useFocus.js';
 
 const ESC = '\u001B';
 // On macOS, when the terminal's Option key is in its default "compose
-// character" mode (iTerm2 "Normal", VS Code without macOptionIsMeta), Option+t
-// is delivered to the app as the dagger glyph "†" (U+2020) with no modifier
-// metadata — so there is no way to tell Option was held. Terminals that speak
-// the Kitty keyboard protocol (e.g. Ghostty) instead report a real Alt+t event,
-// which is why the shortcut already works there. We treat a lone "†" as Alt+t so
-// the "expand thinking" shortcut works everywhere without requiring users to
-// reconfigure their terminal. See handleKeypress for where this is applied.
-const OPTION_T_COMPOSED_GLYPH = '†';
+// character" mode (Terminal.app, iTerm2 "Normal", VS Code without
+// macOptionIsMeta), Option+<key> is delivered to the app as a bare glyph with
+// no modifier metadata — so there is no way to tell Option was held. Terminals
+// that speak the Kitty keyboard protocol (e.g. Ghostty, WezTerm) instead report
+// a real Alt event, which is why those shortcuts already work there. We rewrite
+// each lone glyph to its synthetic Alt equivalent so the shortcuts work
+// everywhere without requiring users to reconfigure their terminal. See
+// handleKeypress for where this is applied.
+const OPTION_COMPOSED_GLYPHS: Record<string, string> = {
+  '†': 't', // Option+t → "expand thinking"
+  '√': 'v', // Option+v → paste clipboard image
+};
 export const PASTE_MODE_PREFIX = `${ESC}[200~`;
 export const PASTE_MODE_SUFFIX = `${ESC}[201~`;
 export const DRAG_COMPLETION_TIMEOUT_MS = 100; // Broadcast full path after 100ms if no more input
@@ -1180,18 +1184,19 @@ export function KeypressProvider({
         key.meta = true;
       }
 
-      // macOS "Option as compose character" terminals turn Option+t into the
-      // bare glyph "†" (U+2020) with no modifier metadata. Rewrite it to a
-      // synthetic Alt+t so the "expand thinking" shortcut fires; the meta flag
-      // also stops the glyph from being inserted into the input buffer (the
-      // text buffer skips printable input when meta/ctrl is set), so it looks
-      // exactly like Alt was pressed.
-      if (
-        process.platform === 'darwin' &&
-        !isPaste &&
-        key.sequence === OPTION_T_COMPOSED_GLYPH
-      ) {
-        key.name = 't';
+      // macOS "Option as compose character" terminals turn Option+<key> into a
+      // bare glyph with no modifier metadata. Rewrite it to a synthetic Alt so
+      // the shortcut fires; the meta flag also stops the glyph from being
+      // inserted into the input buffer (the text buffer skips printable input
+      // when meta/ctrl is set), so it looks exactly like Alt was pressed.
+      const composedKeyName = Object.hasOwn(
+        OPTION_COMPOSED_GLYPHS,
+        key.sequence,
+      )
+        ? OPTION_COMPOSED_GLYPHS[key.sequence]
+        : undefined;
+      if (process.platform === 'darwin' && !isPaste && composedKeyName) {
+        key.name = composedKeyName;
         key.meta = true;
       }