feat(desktop): v2 terminal shows hover tooltip describing cmd-click action

Adds onLinkHover/onLinkLeave callbacks to TerminalLinkHandlers, wired through
LinkDetectorAdapter, UrlLinkProvider, and WordLinkDetector so every detected
link participates.

In v2 TerminalPane, a new LinkHoverTooltip component tracks hover + live
modifier state (global keydown/keyup listeners scoped to hover duration) and
portals a positioned tooltip to document.body when meta/ctrl is held. Content
flips on shift:
- File:   Open in editor       | shift: Open externally
- Folder: Reveal in sidebar    | shift: Open externally
- URL:    Open in browser      | shift: Open in external browser

v1's helpers.ts doesn't opt into the new callbacks, so v1 hover behavior is
unchanged.

Author: saddlepaddle

apps/desktop/src/renderer/lib/terminal/links/link-detector-adapter.ts

@@ -45,6 +45,8 @@ export class LinkDetectorAdapter implements ILinkProvider {
 			event: MouseEvent,
 			link: DetectedLink,
 		) => void,
+		private readonly _onHover?: (event: MouseEvent, link: DetectedLink) => void,
+		private readonly _onLeave?: () => void,
 	) {}
 
 	provideLinks(
@@ -192,6 +194,12 @@ export class LinkDetectorAdapter implements ILinkProvider {
 					activate: (event: MouseEvent) => {
 						this._onActivate?.(event, detected);
 					},
+					hover: (event: MouseEvent) => {
+						this._onHover?.(event, detected);
+					},
+					leave: () => {
+						this._onLeave?.();
+					},
 				});
 			}
 		}
@@ -233,6 +241,12 @@ export class LinkDetectorAdapter implements ILinkProvider {
 				activate: (event: MouseEvent) => {
 					this._onActivate?.(event, detected);
 				},
+				hover: (event: MouseEvent) => {
+					this._onHover?.(event, detected);
+				},
+				leave: () => {
+					this._onLeave?.();
+				},
 			});
 		}
 

apps/desktop/src/renderer/lib/terminal/links/word-link-detector.ts

@@ -52,6 +52,11 @@ export class WordLinkDetector implements ILinkProvider {
 			event: MouseEvent,
 			resolvedPath: string,
 		) => void,
+		private readonly _onHover?: (
+			event: MouseEvent,
+			resolvedPath: string,
+		) => void,
+		private readonly _onLeave?: () => void,
 	) {
 		this._separatorRegex = buildSeparatorRegex(DEFAULT_WORD_SEPARATORS);
 	}
@@ -108,6 +113,12 @@ export class WordLinkDetector implements ILinkProvider {
 				activate: (event: MouseEvent) => {
 					this._onActivate?.(event, resolved.path);
 				},
+				hover: (event: MouseEvent) => {
+					this._onHover?.(event, resolved.path);
+				},
+				leave: () => {
+					this._onLeave?.();
+				},
 			});
 		}
 

apps/desktop/src/renderer/lib/terminal/terminal-link-manager.ts

@@ -18,6 +18,10 @@ import {
 	WordLinkDetector,
 } from "./links";
 
+export type LinkHoverInfo =
+	| { kind: "file"; isDirectory: boolean }
+	| { kind: "url" };
+
 /**
  * Link handler callbacks for the v2 terminal.
  */
@@ -26,6 +30,10 @@ export interface TerminalLinkHandlers {
 	onFileLinkClick?: (event: MouseEvent, link: DetectedLink) => void;
 	/** Called when a URL link is activated. */
 	onUrlClick?: (event: MouseEvent, url: string) => void;
+	/** Called when the mouse enters a detected link (file path or URL). */
+	onLinkHover?: (event: MouseEvent, info: LinkHoverInfo) => void;
+	/** Called when the mouse leaves a previously hovered link. */
+	onLinkLeave?: () => void;
 	/**
 	 * Stat callback to validate file paths exist. Called via the host service
 	 * which handles all path resolution (relative, tilde, etc.) server-side.
@@ -93,21 +101,39 @@ export class TerminalLinkManager {
 			this._resolver = new TerminalLinkResolver(handlers.stat);
 		}
 
+		const onLinkHover = handlers.onLinkHover;
+		const onLinkLeave = handlers.onLinkLeave;
+
 		// 1. File path detector (highest priority)
 		const detector = new LocalLinkDetector(this._resolver);
 		const adapter = new LinkDetectorAdapter(
 			this._terminal,
 			detector,
 			handlers.onFileLinkClick,
+			onLinkHover
+				? (event, link) =>
+						onLinkHover(event, {
+							kind: "file",
+							isDirectory: link.isDirectory,
+						})
+				: undefined,
+			onLinkLeave,
 		);
 		this._disposables.push(this._terminal.registerLinkProvider(adapter));
 
 		// 2. URL link provider (handles hard-wrapped URLs)
 		if (handlers.onUrlClick) {
 			const onUrlClick = handlers.onUrlClick;
-			const urlProvider = new UrlLinkProvider(this._terminal, (event, uri) => {
-				onUrlClick(event, uri);
-			});
+			const urlProvider = new UrlLinkProvider(
+				this._terminal,
+				(event, uri) => {
+					onUrlClick(event, uri);
+				},
+				onLinkHover
+					? (event) => onLinkHover(event, { kind: "url" })
+					: undefined,
+				onLinkLeave,
+			);
 			this._disposables.push(this._terminal.registerLinkProvider(urlProvider));
 		}
 
@@ -135,6 +161,10 @@ export class TerminalLinkManager {
 						colEnd: undefined,
 					});
 				},
+				onLinkHover
+					? (event) => onLinkHover(event, { kind: "file", isDirectory: false })
+					: undefined,
+				onLinkLeave,
 			);
 			this._disposables.push(this._terminal.registerLinkProvider(wordDetector));
 		}

apps/desktop/src/renderer/lib/terminal/terminal-runtime-registry.ts

@@ -2,6 +2,7 @@ import type { ProgressAddon } from "@xterm/addon-progress";
 import type { SearchAddon } from "@xterm/addon-search";
 import type { TerminalAppearance } from "./appearance";
 import {
+	type LinkHoverInfo,
 	type TerminalLinkHandlers,
 	TerminalLinkManager,
 } from "./terminal-link-manager";
@@ -216,4 +217,4 @@ if (import.meta.hot) {
 	import.meta.hot.data.registry = terminalRuntimeRegistry;
 }
 
-export type { ConnectionState, TerminalLinkHandlers };
+export type { ConnectionState, LinkHoverInfo, TerminalLinkHandlers };

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/$workspaceId/hooks/usePaneRegistry/components/TerminalPane/TerminalPane.tsx

@@ -25,6 +25,10 @@ import { ScrollToBottomButton } from "renderer/screens/main/components/Workspace
 import { TerminalSearch } from "renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/TerminalSearch";
 import { useTheme } from "renderer/stores/theme";
 import { resolveTerminalThemeType } from "renderer/stores/theme/utils";
+import {
+	LinkHoverTooltip,
+	useLinkHoverState,
+} from "./components/LinkHoverTooltip";
 import { useTerminalAppearance } from "./hooks/useTerminalAppearance";
 
 interface TerminalPaneProps {
@@ -50,6 +54,11 @@ export function TerminalPane({
 	onRevealPath,
 }: TerminalPaneProps) {
 	const openInExternalEditor = useOpenInExternalEditor(workspaceId);
+	const {
+		hoveredLink,
+		onHover: onLinkHover,
+		onLeave: onLinkLeave,
+	} = useLinkHoverState();
 	const paneData = ctx.pane.data as TerminalPaneData;
 	const { terminalId } = paneData;
 	const containerRef = useRef<HTMLDivElement | null>(null);
@@ -180,6 +189,8 @@ export function TerminalPane({
 					},
 				});
 			},
+			onLinkHover,
+			onLinkLeave,
 		});
 	}, [
 		terminalId,
@@ -188,6 +199,8 @@ export function TerminalPane({
 		onOpenFile,
 		onRevealPath,
 		openInExternalEditor,
+		onLinkHover,
+		onLinkLeave,
 	]);
 
 	useHotkey(
@@ -244,6 +257,7 @@ export function TerminalPane({
 					<span>Disconnected</span>
 				</div>
 			)}
+			<LinkHoverTooltip hoveredLink={hoveredLink} />
 		</div>
 	);
 }

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/$workspaceId/hooks/usePaneRegistry/components/TerminalPane/components/LinkHoverTooltip/LinkHoverTooltip.tsx

@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import type { LinkHoverInfo } from "renderer/lib/terminal/terminal-runtime-registry";
+
+interface HoveredLink {
+	clientX: number;
+	clientY: number;
+	info: LinkHoverInfo;
+	modifier: boolean;
+	shift: boolean;
+}
+
+interface LinkHoverTooltipProps {
+	hoveredLink: HoveredLink | null;
+}
+
+function getLabel(info: LinkHoverInfo, shift: boolean): string {
+	if (info.kind === "url") {
+		return shift ? "Open in external browser" : "Open in browser";
+	}
+	if (info.isDirectory) {
+		return shift ? "Open externally" : "Reveal in sidebar";
+	}
+	return shift ? "Open externally" : "Open in editor";
+}
+
+export function LinkHoverTooltip({ hoveredLink }: LinkHoverTooltipProps) {
+	if (!hoveredLink || !hoveredLink.modifier) return null;
+
+	const label = getLabel(hoveredLink.info, hoveredLink.shift);
+
+	return createPortal(
+		<div
+			className="pointer-events-none fixed z-50 rounded-md border border-border bg-popover px-2 py-1 text-xs text-popover-foreground shadow-md"
+			style={{
+				left: hoveredLink.clientX + 14,
+				top: hoveredLink.clientY + 14,
+			}}
+		>
+			{label}
+		</div>,
+		document.body,
+	);
+}
+
+export function useLinkHoverState() {
+	const [hoveredLink, setHoveredLink] = useState<HoveredLink | null>(null);
+
+	useEffect(() => {
+		if (!hoveredLink) return;
+		const update = (event: KeyboardEvent) => {
+			setHoveredLink((prev) => {
+				if (!prev) return null;
+				return {
+					...prev,
+					modifier: event.metaKey || event.ctrlKey,
+					shift: event.shiftKey,
+				};
+			});
+		};
+		window.addEventListener("keydown", update);
+		window.addEventListener("keyup", update);
+		return () => {
+			window.removeEventListener("keydown", update);
+			window.removeEventListener("keyup", update);
+		};
+	}, [hoveredLink]);
+
+	const onHover = useCallback((event: MouseEvent, info: LinkHoverInfo) => {
+		setHoveredLink({
+			clientX: event.clientX,
+			clientY: event.clientY,
+			info,
+			modifier: event.metaKey || event.ctrlKey,
+			shift: event.shiftKey,
+		});
+	}, []);
+
+	const onLeave = useCallback(() => {
+		setHoveredLink(null);
+	}, []);
+
+	return { hoveredLink, onHover, onLeave };
+}

apps/desktop/src/renderer/routes/_authenticated/_dashboard/v2-workspace/$workspaceId/hooks/usePaneRegistry/components/TerminalPane/components/LinkHoverTooltip/index.ts

@@ -0,0 +1 @@
+export { LinkHoverTooltip, useLinkHoverState } from "./LinkHoverTooltip";

apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/link-providers/multi-line-link-provider.ts

@@ -42,6 +42,10 @@ export abstract class MultiLineLinkProvider implements ILinkProvider {
 		regexMatch: RegExpMatchArray,
 	): void;
 
+	/** Optional hooks fired when the mouse enters/leaves a detected link. */
+	protected handleHover?(event: MouseEvent, text: string): void;
+	protected handleLeave?(): void;
+
 	/**
 	 * Optional hook to transform a match before creating the link.
 	 * Useful for stripping trailing characters. Return null to skip the match.
@@ -177,6 +181,12 @@ export abstract class MultiLineLinkProvider implements ILinkProvider {
 					activate: (event: MouseEvent, text: string) => {
 						this.handleActivation(event, text, match);
 					},
+					hover: (event: MouseEvent, text: string) => {
+						this.handleHover?.(event, text);
+					},
+					leave: () => {
+						this.handleLeave?.();
+					},
 				});
 			}
 		}

apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/link-providers/url-link-provider.ts

@@ -313,10 +313,20 @@ export class UrlLinkProvider extends MultiLineLinkProvider {
 	constructor(
 		terminal: Terminal,
 		private readonly onOpen: (event: MouseEvent, uri: string) => void,
+		private readonly onHover?: (event: MouseEvent, uri: string) => void,
+		private readonly onLeave?: () => void,
 	) {
 		super(terminal);
 	}
 
+	protected handleHover(event: MouseEvent, text: string): void {
+		this.onHover?.(event, text);
+	}
+
+	protected handleLeave(): void {
+		this.onLeave?.();
+	}
+
 	protected getPattern(): RegExp {
 		return new RegExp(this.URL_PATTERN.source, "g");
 	}