fix(ui): improve clipboard reliability across terminals

src/ui/chat.tsx

@@ -58,6 +58,7 @@ import { saveTasksToActiveSession } from "./commands/workflow-commands.ts";
 import { type ToolExecutionStatus } from "./parts/types.ts";
 import { useMessageQueue, type QueuedMessage } from "./hooks/use-message-queue.ts";
 import { useVerboseMode } from "./hooks/use-verbose-mode.ts";
+
 import {
   globalRegistry,
   parseSlashCommand,
@@ -95,6 +96,7 @@ import {
   isBackgroundTerminationKey,
 } from "./utils/background-agent-termination.ts";
 import { loadCommandHistory, appendCommandHistory } from "./utils/command-history.ts";
+import { createClipboardAdapter, type ClipboardAdapter } from "./utils/clipboard.ts";
 import type { McpServerToggleMap, McpSnapshotView } from "./utils/mcp-output.ts";
 import {
   normalizeHitlAnswer,
@@ -2250,6 +2252,15 @@ export function ChatApp({
   // Renderer ref for copy-on-selection (OpenTUI Selection API)
   const renderer = useRenderer();
 
+  // Platform-aware clipboard adapter (Strategy pattern).
+  // Tries OSC 52 first; falls back to native commands (pbcopy, xclip, etc.)
+  // on terminals that don't support OSC 52 (macOS Terminal.app, VS Code).
+  const clipboardRef = useRef<ClipboardAdapter | null>(null);
+  if (!clipboardRef.current) {
+    clipboardRef.current = createClipboardAdapter(renderer);
+  }
+  const clipboard = clipboardRef.current;
+
   // Copy-on-selection: auto-copy selected text to clipboard on mouse release
   // Keep selection visible so user can also use Ctrl+C / Ctrl+Shift+C to copy
   const handleMouseUp = useCallback(() => {
@@ -2258,14 +2269,13 @@ export function ChatApp({
       if (selection) {
         const selectedText = selection.getSelectedText();
         if (selectedText) {
-          // Type assertion for method that exists at runtime but not in type definitions
-          (renderer as unknown as { copyToClipboardOSC52: (text: string) => void }).copyToClipboardOSC52(selectedText);
+          clipboard.copy(selectedText);
         }
       }
     } catch {
       // Ignore errors from mouse selection — can occur when renderables are in a transitional state
     }
-  }, [renderer]);
+  }, [renderer, clipboard]);
 
   // Pending questions queue for HITL flow
   const [, setPendingQuestions] = useState<UserQuestion[]>([]);
@@ -2296,6 +2306,7 @@ export function ChatApp({
   // Verbose mode: shows timestamps, model info on messages (ctrl+e toggle)
   const { toggle: toggleVerbose } = useVerboseMode();
 
+
   // State for showing user question dialog
   const [activeQuestion, setActiveQuestion] = useState<UserQuestion | null>(null);
 
@@ -6171,18 +6182,16 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
   }, []);
 
   // Handle clipboard copy - copies selected text to system clipboard
+  // Uses the platform-aware clipboard adapter (OSC 52 → native fallback)
   // Checks both textarea selection and renderer (mouse-drag) selection
   const handleCopy = useCallback(() => {
     const textarea = textareaRef.current;
-    // Type assertion for method that exists at runtime but not in type definitions
-    const copyToClipboard = (text: string) =>
-      (renderer as unknown as { copyToClipboardOSC52: (text: string) => void }).copyToClipboardOSC52(text);
 
     // First, check textarea selection (input area)
     if (textarea?.hasSelection()) {
       const selectedText = textarea.getSelectedText();
       if (selectedText) {
-        copyToClipboard(selectedText);
+        clipboard.copy(selectedText);
         return;
       }
     }
@@ -6192,11 +6201,11 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
     if (selection) {
       const selectedText = selection.getSelectedText();
       if (selectedText) {
-        copyToClipboard(selectedText);
+        clipboard.copy(selectedText);
         renderer.clearSelection();
       }
     }
-  }, [renderer]);
+  }, [renderer, clipboard]);
 
   // Handle bracketed paste events from OpenTUI
   // This is the primary paste handler for modern terminals that support bracketed paste mode
@@ -6228,8 +6237,8 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           event.raw,
         );
 
-        // Ctrl+C handling must work everywhere (even in dialogs) for double-press exit
-        if (event.ctrl && event.name === "c") {
+        // Ctrl+C / Cmd+C handling must work everywhere (even in dialogs) for double-press exit
+        if ((event.ctrl || event.meta) && event.name === "c") {
           const textarea = textareaRef.current;
           // If textarea or renderer has selection and no dialog is active, copy instead of interrupt/exit
           const hasRendererSelection = !!renderer.getSelection()?.getSelectedText();
@@ -6567,6 +6576,7 @@ Important: Do not add any text before or after the sub-agent's output. Pass thro
           return;
         }
 
+
         // Skip other keyboard handling when a dialog is active
         // The dialog components handle their own keyboard events via their own useKeyboard hooks
         if (activeQuestion || showModelSelector) {

src/ui/index.ts

@@ -624,7 +624,11 @@ export async function startChatUI(
     }
 
     // Create the CLI renderer with:
-    // - mouse mode enabled for scroll wheel support (text selection via OpenTUI Selection API + Ctrl+Shift+C)
+    // - mouse tracking ENABLED for scroll-wheel support in scrollboxes and
+    //   OpenTUI Selection API (mouse-drag to select, auto-copy on release).
+    //   For native terminal text selection, hold Shift (Linux/Windows) or
+    //   Option (macOS/iTerm2) while clicking — this is a built-in terminal
+    //   emulator bypass that works with virtually all modern terminals.
     // - useAlternateScreen: true to prevent scrollbox from corrupting terminal output
     // - exitOnCtrlC: false to allow double-press Ctrl+C behavior
     // - useKittyKeyboard: with disambiguate so Ctrl+C is received as keyboard event

src/ui/utils/clipboard.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Tests for ClipboardAdapter — platform-aware clipboard write strategy.
+ *
+ * Validates:
+ *   1. OSC 52 path is preferred when terminal reports support
+ *   2. Native command fallback fires when OSC 52 is not available
+ *   3. Chained fallback works (primary fails → secondary attempted)
+ *   4. `detectNativeClipboardCommand` resolution per platform
+ */
+
+import { describe, test, expect, mock, beforeEach, afterEach, spyOn } from "bun:test";
+import { createClipboardAdapter } from "./clipboard.ts";
+import type { CliRenderer } from "@opentui/core";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Minimal mock that satisfies the renderer surface used by ClipboardAdapter */
+function makeMockRenderer(overrides: {
+  osc52Supported?: boolean;
+  copyResult?: boolean;
+} = {}): CliRenderer {
+  const { osc52Supported = false, copyResult = true } = overrides;
+  return {
+    isOsc52Supported: mock(() => osc52Supported),
+    copyToClipboardOSC52: mock(() => copyResult),
+  } as unknown as CliRenderer;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("ClipboardAdapter", () => {
+  const originalTermProgram = process.env.TERM_PROGRAM;
+
+  beforeEach(() => {
+    // Ensure default path tests don't accidentally inherit Apple Terminal,
+    // which intentionally prefers native clipboard over OSC 52.
+    process.env.TERM_PROGRAM = "iTerm.app";
+  });
+
+  afterEach(() => {
+    process.env.TERM_PROGRAM = originalTermProgram;
+  });
+
+  describe("when OSC 52 is supported", () => {
+    test("uses OSC 52 for copy", () => {
+      const renderer = makeMockRenderer({ osc52Supported: true, copyResult: true });
+      const adapter = createClipboardAdapter(renderer);
+
+      const result = adapter.copy("hello");
+
+      expect(result).toBe(true);
+      expect(renderer.copyToClipboardOSC52).toHaveBeenCalledWith("hello");
+    });
+
+    test("returns true when OSC 52 succeeds", () => {
+      const renderer = makeMockRenderer({ osc52Supported: true, copyResult: true });
+      const adapter = createClipboardAdapter(renderer);
+
+      expect(adapter.copy("test")).toBe(true);
+    });
+
+    test("falls back to native clipboard when OSC 52 write fails", () => {
+      const renderer = makeMockRenderer({ osc52Supported: true, copyResult: false });
+      const whichSpy = spyOn(Bun, "which").mockImplementation((cmd: string) => {
+        if (cmd === "pbcopy") return "/usr/bin/pbcopy" as ReturnType<typeof Bun.which>;
+        return null as ReturnType<typeof Bun.which>;
+      });
+      const spawnSpy = spyOn(Bun, "spawnSync").mockReturnValue({
+        success: true,
+      } as ReturnType<typeof Bun.spawnSync>);
+
+      const adapter = createClipboardAdapter(renderer);
+      const result = adapter.copy("hello");
+
+      expect(result).toBe(true);
+      expect(renderer.copyToClipboardOSC52).toHaveBeenCalledWith("hello");
+      expect(spawnSpy).toHaveBeenCalled();
+
+      spawnSpy.mockRestore();
+      whichSpy.mockRestore();
+    });
+
+    test("prefers native clipboard on Apple Terminal even if OSC 52 is reported", () => {
+      process.env.TERM_PROGRAM = "Apple_Terminal";
+
+      const renderer = makeMockRenderer({ osc52Supported: true, copyResult: true });
+      const whichSpy = spyOn(Bun, "which").mockImplementation((cmd: string) => {
+        if (cmd === "pbcopy") return "/usr/bin/pbcopy" as ReturnType<typeof Bun.which>;
+        return null as ReturnType<typeof Bun.which>;
+      });
+      const spawnSpy = spyOn(Bun, "spawnSync").mockReturnValue({
+        success: true,
+      } as ReturnType<typeof Bun.spawnSync>);
+
+      const adapter = createClipboardAdapter(renderer);
+      const result = adapter.copy("hello");
+
+      expect(result).toBe(true);
+      expect(spawnSpy).toHaveBeenCalled();
+      expect((renderer.copyToClipboardOSC52 as ReturnType<typeof mock>).mock.calls.length).toBe(0);
+
+      spawnSpy.mockRestore();
+      whichSpy.mockRestore();
+    });
+  });
+
+  describe("when OSC 52 is NOT supported", () => {
+    test("does not call OSC 52 as primary", () => {
+      const renderer = makeMockRenderer({ osc52Supported: false });
+      const adapter = createClipboardAdapter(renderer);
+
+      // On macOS (our test platform), this will attempt pbcopy as the native fallback.
+      // The copy result depends on platform availability, but OSC 52 should NOT be the
+      // primary path. We verify by checking that the adapter was created successfully
+      // and doesn't throw.
+      const result = adapter.copy("hello");
+      // On macOS with pbcopy available, this should succeed via native fallback
+      if (process.platform === "darwin") {
+        expect(result).toBe(true);
+      }
+      // Regardless of platform, the adapter should not throw
+      expect(typeof result).toBe("boolean");
+    });
+  });
+
+  describe("strategy resolution", () => {
+    test("adapter is reusable across multiple copy calls", () => {
+      const renderer = makeMockRenderer({ osc52Supported: true, copyResult: true });
+      const adapter = createClipboardAdapter(renderer);
+
+      adapter.copy("first");
+      adapter.copy("second");
+      adapter.copy("third");
+
+      // isOsc52Supported is called once for lazy strategy resolution
+      expect((renderer.isOsc52Supported as ReturnType<typeof mock>).mock.calls.length).toBe(1);
+      // copyToClipboardOSC52 is called for each copy
+      expect((renderer.copyToClipboardOSC52 as ReturnType<typeof mock>).mock.calls.length).toBe(3);
+    });
+
+    test("strategy resolution is lazy (deferred until first copy)", () => {
+      const renderer = makeMockRenderer({ osc52Supported: true });
+      createClipboardAdapter(renderer);
+
+      // No calls until copy() is invoked
+      expect((renderer.isOsc52Supported as ReturnType<typeof mock>).mock.calls.length).toBe(0);
+    });
+
+    test("empty string is handled without error", () => {
+      const renderer = makeMockRenderer({ osc52Supported: true, copyResult: true });
+      const adapter = createClipboardAdapter(renderer);
+
+      expect(() => adapter.copy("")).not.toThrow();
+    });
+  });
+
+  describe("native fallback on macOS", () => {
+    test.skipIf(process.platform !== "darwin")(
+      "pbcopy fallback writes to system clipboard",
+      () => {
+        // OSC 52 not supported → should fall back to pbcopy on macOS
+        const renderer = makeMockRenderer({ osc52Supported: false });
+        const adapter = createClipboardAdapter(renderer);
+
+        const testText = `clipboard-test-${Date.now()}`;
+        const result = adapter.copy(testText);
+        expect(result).toBe(true);
+
+        // Verify by reading back with pbpaste
+        const readBack = Bun.spawnSync({
+          cmd: ["pbpaste"],
+          stdout: "pipe",
+        });
+        expect(readBack.stdout.toString()).toBe(testText);
+      }
+    );
+  });
+});