fix(terminal): prioritize selected copy menu

Handle selected-output context menus during capture so xterm and the browser cannot open a competing menu.

apps/web/src/components/features/terminal/terminal.test.ts

@@ -4,7 +4,7 @@ import {
 	getTerminalScrollbackLimit,
 	isCurrentWebSocket,
 	shouldRetryWebSocketClose,
-	shouldCopyTerminalSelection,
+	shouldShowTerminalCopyMenu,
 } from "./terminal.tsx";
 
 describe("getTerminalScrollbackLimit", () => {
@@ -32,28 +32,12 @@ describe("getTerminalScrollbackLimit", () => {
 	});
 });
 
-describe("shouldCopyTerminalSelection", () => {
+describe("shouldShowTerminalCopyMenu", () => {
-	it("copies a selected terminal region with Ctrl+C or Cmd+C", () => {
+	it("shows Copy for selected terminal output", () => {
-		expect(
+		expect(shouldShowTerminalCopyMenu("selected output")).toBe(true);
-			shouldCopyTerminalSelection(
-				{ ctrlKey: true, metaKey: false, key: "c" },
-				true,
-			),
-		).toBe(true);
-		expect(
-			shouldCopyTerminalSelection(
-				{ ctrlKey: false, metaKey: true, key: "C" },
-				true,
-			),
-		).toBe(true);
 	});
 
-	it("keeps Ctrl+C as a terminal interrupt without a selection", () => {
+	it("keeps the native context menu when no output is selected", () => {
-		expect(
+		expect(shouldShowTerminalCopyMenu("")).toBe(false);
-			shouldCopyTerminalSelection(
-				{ ctrlKey: true, metaKey: false, key: "c" },
-				false,
-			),
-		).toBe(false);
 	});
 });

apps/web/src/components/features/terminal/terminal.tsx

@@ -68,15 +68,20 @@ export function shouldRetryWebSocketClose(code: number, reason: string): boolean
 	return code !== 1000 && !(code === 4000 && reason === "New connection established");
 }
 
-export function shouldCopyTerminalSelection(
+export function shouldShowTerminalCopyMenu(selection: string): boolean {
-	event: Pick<KeyboardEvent, "ctrlKey" | "metaKey" | "key">,
+	return selection.length > 0;
-	hasSelection: boolean,
+}
-): boolean {
+
-	return (
+function copyTextWithFallback(text: string): void {
-		hasSelection &&
+	const textarea = document.createElement("textarea");
-		(event.ctrlKey || event.metaKey) &&
+	textarea.value = text;
-		event.key.toLowerCase() === "c"
+	textarea.setAttribute("readonly", "");
-	);
+	textarea.style.position = "fixed";
+	textarea.style.opacity = "0";
+	document.body.appendChild(textarea);
+	textarea.select();
+	document.execCommand("copy");
+	textarea.remove();
 }
 
 function matchesByteSequence(
@@ -118,6 +123,11 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 		>("connecting");
 		const [error, setError] = useState<string | null>(null);
 		const [showResetConfirm, setShowResetConfirm] = useState(false);
+		const [copyMenu, setCopyMenu] = useState<{
+			x: number;
+			y: number;
+			text: string;
+		} | null>(null);
 		const activeModifierRef = useRef(activeModifier);
 		activeModifierRef.current = activeModifier;
 		const [fontSize, setFontSize] = useState(() => {
@@ -480,27 +490,16 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 				event.preventDefault();
 				event.clipboardData?.setData("text/plain", selection);
 			};
-			const copySelection = () => {
+			const handleTerminalContextMenu = (event: MouseEvent) => {
 				const selection = term.getSelection();
-				if (!selection) return;
+				if (!shouldShowTerminalCopyMenu(selection)) {
-				const clipboard = navigator.clipboard;
+					setCopyMenu(null);
-				if (clipboard) {
+					return;
-					void clipboard.writeText(selection).catch(() => {
-						document.execCommand("copy");
-					});
-				} else {
-					document.execCommand("copy");
-				}
-			};
-			term.attachCustomKeyEventHandler((event) => {
-				if (!shouldCopyTerminalSelection(event, term.hasSelection())) {
-					return true;
 				}
 
 				event.preventDefault();
-				copySelection();
+				setCopyMenu({ x: event.clientX, y: event.clientY, text: selection });
-				return false;
+			};
-			});
 
 			const handleBrowserPaste = (event: ClipboardEvent) => {
 				const text = event.clipboardData?.getData("text/plain");
@@ -513,6 +512,7 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 				pasteTextRef.current(text);
 			};
 			container.addEventListener("copy", handleBrowserCopy, true);
+			container.addEventListener("contextmenu", handleTerminalContextMenu, true);
 			container.addEventListener("paste", handleBrowserPaste, true);
 
 			// Mobile touch scroll.
@@ -761,6 +761,11 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 				);
 				if (touchCleanup) touchCleanup();
 				container.removeEventListener("copy", handleBrowserCopy, true);
+				container.removeEventListener(
+					"contextmenu",
+					handleTerminalContextMenu,
+					true,
+				);
 				container.removeEventListener("paste", handleBrowserPaste, true);
 				pasteTextRef.current = () => {};
 				bracketedPasteEnabledRef.current = false;
@@ -895,6 +900,7 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 
 		// Focus terminal on mobile to keep keyboard open
 		const handleTerminalClick = () => {
+			setCopyMenu(null);
 			if (isMobile && termRef.current) {
 				termRef.current.focus();
 			}
@@ -1009,6 +1015,26 @@ export const TerminalComponent = React.forwardRef<TerminalRef, TerminalProps>(
 						</div>
 					</div>
 				)}
+				{copyMenu && (
+					<button
+						aria-label="Copy selected terminal text"
+						className="terminal-context-copy"
+						onMouseDown={(event) => {
+							event.preventDefault();
+							copyTextWithFallback(copyMenu.text);
+							setCopyMenu(null);
+						}}
+						style={{
+							left: copyMenu.x,
+							position: "fixed",
+							top: copyMenu.y,
+							zIndex: 1000,
+						}}
+						type="button"
+					>
+						Copy
+					</button>
+				)}
 				{error && (
 					<div className="terminal-error">
 						{error}

openspec/changes/fix-web-terminal-clipboard/change.md

@@ -6,7 +6,9 @@ Users cannot reliably copy terminal output from the browser terminal. Browser co
 
 ## Required behavior
 
-- Copying a selected terminal region with standard browser shortcuts (`Ctrl/Cmd+C`) copies text to the system clipboard without sending an interrupt to the terminal.
+- Right-clicking a selected terminal region presents an xterm-aware Copy action that writes the selection to the system clipboard.
+- Browser native context menus remain available when no terminal output is selected.
+- Terminal keyboard input, including `Ctrl+C`, remains unchanged.
 - Copy requests expose the xterm selection as plain text.
 - Pasting plain text is handled once and follows bracketed-paste mode when enabled.
 - Normal terminal interrupts still work when there is no active selection.