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.

feat(file-links): hover shows the resolved path; Shift+Cmd/Ctrl+click opens with the OS app

review4275effa6e3b
diff --git a/CLAUDE.md b/CLAUDE.md
index 928b00f7b..4d40995b7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1405,6 +1405,27 @@ session.
Downloads report in a `DownloadStrip` floated over the terminal, not in a drawer that may be
shut. The kanban card modal gets URL rows only (no file links there) and no "Open in canvas
browser" (the node would land under the board).
+ **Hovering a link says what a click opens** (`terminal/link-hover.ts`): the RESOLVED absolute
+ path — which of the two cwds held it — plus the gestures, `<abs> (⌘-click to open · ⇧⌘-click to
+ open with default app)` (Ctrl/Shift+Ctrl off-mac; a directory reads "reveal" / "open in
+ Finder|file manager"; a URL just `<url> (⌘-click to open)`, OSC 8 included, whose target the label
+ hides). It rides xterm's `ILink.hover`/`leave`, which fire in a tmux pane too — the linkifier
+ listens to `mousemove` on the screen element whatever the mouse-tracking mode; only CLICKS need
+ the capture fallback. One tooltip per xterm instance, INSIDE `term.element` (parks and dies with
+ the terminal, scales with the canvas zoom like the copy pill; positioned by dividing the rect by
+ the rendered/layout width ratio), `pointer-events: none` + `xterm-hover`, hidden by any press or
+ wheel. **Shift+Cmd/Ctrl+click opens with the OS default app** (`linkOpenIntent` — ONE routing rule
+ for the provider `activate` and `installLinkClickFallback`): `shell.openPath` behind
+ `canUseLocalShell`, the same gate as Reveal in Finder, so a directory opens in the OS file
+ manager. Everywhere that gate says no the click TOASTS its reason (`systemOpenRefusal`) and the
+ hint omits the gesture: an SSH project is refused rather than downloaded-then-opened (a click must
+ not silently copy a file or folder to this machine, and edits would land on a stale copy — the
+ link menu's Download is one right-click away), the Server Edition is refused rather than falling
+ back to the plain open (a modified gesture that quietly does something else is harder to learn;
+ the bridge's `shell.openPath` stays its documented inert stub), and a relay tab is refused (the
+ path is on the peer). Shift alone is never a link gesture (xterm's selection modifier); a
+ modified press released on another cell is a drag and is left alone, and a Shift+Cmd click that
+ extended an xterm selection does not open.
**Home-relative `~/x` tokens** (Claude Code prints its plan file as `~/.claude/plans/<name>.md`)
stay `~`-rooted all the way to the fs call and are expanded by the core that OWNS the filesystem
— `expandHomePath` in `core/fs-handlers.ts` for desktop/Server Edition, the remote shell for
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 98f3ff5af..eae24e2e9 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -51,12 +51,20 @@ import {
findExistingPath,
fileMissMessage,
makeDirListingLookup,
+ type LinkHoverSink,
type UnverifiedPath
} from '../terminal/file-links'
import { linkMenuItems, resolveLinkTarget, type LinkMenuTarget } from '../terminal/link-menu'
import { ContextMenu } from '../components/ContextMenu'
import { DownloadStrip } from '../components/DownloadStrip'
-import { canUseLocalShell, downloadRoute } from '../lib/download'
+import { canUseLocalShell, downloadRoute, type DownloadContext } from '../lib/download'
+import {
+ createLinkHintTooltip,
+ fileLinkHint,
+ hideLinkHints,
+ systemOpenRefusal,
+ urlLinkHint
+} from '../terminal/link-hover'
import { useDownloads } from '../lib/useDownloads'
import { fileLinkDialect } from '../terminal/file-link-dialect'
import { hostPlatformFor } from '../terminal/host-platform'
@@ -3058,6 +3066,8 @@ export function TerminalNode({
// Reattach the parked xterm's DOM element: the PTY never detached, so the screen is
// already current — no spawn, no tmux redraw, no terminal-mode re-negotiation.
if (term.element) container.appendChild(term.element)
+ // A link tooltip showing when the terminal parked would otherwise reappear where it was.
+ if (term.element) hideLinkHints(term.element)
applyFit()
} else {
term.loadAddon(fit)
@@ -3094,13 +3104,43 @@ export function TerminalNode({
// agent TUI paints, so a long OAuth URL matched only its first row's fragment); file
// paths → editor node / Explorer reveal via the file provider. Both are modifier-gated
// inside their activate handlers, so plain clicks stay selections.
+ // Hovering a link names what a click will open — the RESOLVED path (the launch cwd or the
+ // pane's live cwd, whichever held it) and the gestures (link-hover.ts). One tooltip per xterm
+ // instance, inside its element, so it parks and dies with the terminal.
+ const linkHint = term.element ? createLinkHintTooltip(term.element) : null
+ // Read at hover/click time, never captured: the active project can change under a parked
+ // terminal. `projectFs` is declared below and only called after this block has run.
+ const shellCtx = (): DownloadContext => ({
+ browser: isBrowserRuntime(),
+ ssh: projectFs().ssh,
+ source: session.source
+ })
+ const hoverSink: LinkHoverSink | undefined = linkHint
+ ? {
+ hover: (target, ev) =>
+ linkHint.show(
+ target.kind === 'url'
+ ? urlLinkHint(target.url, isMac)
+ : fileLinkHint({
+ abs: target.abs,
+ dir: target.dir,
+ mac: isMac,
+ systemOpen: systemOpenRefusal(shellCtx(), target.abs) === null
+ }),
+ ev.clientX,
+ ev.clientY
+ ),
+ leave: () => linkHint.hide()
+ }
+ : undefined
term.registerLinkProvider(
- createUrlLinkProvider(term, (uri) => window.nodeTerminal.shell.openExternal(uri))
+ createUrlLinkProvider(term, (uri) => window.nodeTerminal.shell.openExternal(uri), hoverSink)
)
// Not in xtermOptionsFromSettings: the handler closes over the shell bridge, which the
// pure options builder must not know.
- term.options.linkHandler = createOsc8LinkHandler((uri) =>
- window.nodeTerminal.shell.openExternal(uri)
+ term.options.linkHandler = createOsc8LinkHandler(
+ (uri) => window.nodeTerminal.shell.openExternal(uri),
+ hoverSink
)
const projectFs = (): { fs: FsApi; ssh: boolean } => {
const st = useProjects.getState()
@@ -3149,12 +3189,26 @@ export function TerminalNode({
new CustomEvent('nodeterm:open-file', { detail: { path: abs, ssh: projectFs().ssh } })
)
}
+ // Shift+Cmd/Ctrl+click → the OS default app (a directory → the OS file manager). The same
+ // `shell.openPath` the files node and ⌘K quick-open use, behind the same `canUseLocalShell`
+ // gate as the link menu's Reveal in Finder; anywhere it cannot act (SSH project, browser tab,
+ // relay) the click says why instead of doing nothing — see `systemOpenRefusal`.
+ const openWithSystem = (abs: string): void => {
+ const why = systemOpenRefusal(shellCtx(), abs)
+ if (why) {
+ window.dispatchEvent(new CustomEvent('nodeterm:toast', { detail: { kind: 'error', message: why } }))
+ return
+ }
+ window.nodeTerminal.shell.openPath(abs)
+ }
term.registerLinkProvider(
createFileLinkProvider(term, {
getCwd,
getLiveCwd,
lookup,
activate: openFile,
+ openWithSystem,
+ hoverSink,
convention: pathConvention
})
)
@@ -3168,6 +3222,7 @@ export function TerminalNode({
getLiveCwd,
lookup,
activateFile: openFile,
+ openFileWithSystem: openWithSystem,
onMissing: onMissingFile,
openUrl: (uri) => window.nodeTerminal.shell.openExternal(uri),
fileEnabled: () => pathConvention() !== null,
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 0ea7b8e11..876a207d6 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -2631,6 +2631,27 @@ body,
border-color: var(--border);
}
+/* Hovering a terminal link names what a click opens — the resolved path + the gestures
+ (terminal/link-hover.ts). Lives INSIDE the xterm element (`.xterm` is position:relative), so it
+ scales with the terminal text like the copy pill; same quiet chrome as the pill's hint variant.
+ `pointer-events: none`: it must never take a click, wheel or hover from the terminal under it. */
+.term-link-hint {
+ position: absolute;
+ z-index: 10;
+ max-width: calc(100% - 8px);
+ pointer-events: none;
+ font-size: 11px;
+ line-height: 1.35;
+ padding: 4px 8px;
+ border-radius: 7px;
+ color: var(--text);
+ background: color-mix(in srgb, var(--bg) 92%, transparent);
+ border: 1px solid var(--border);
+ box-shadow: 0 4px 14px rgb(0 0 0 / 35%);
+ overflow-wrap: anywhere;
+ white-space: normal;
+}
+
/* Downloads started from a terminal link's right-click menu (terminal/link-menu.ts): the shared
`.ex-dls` strip, floated over the terminal's bottom-right like the copy receipt above — one
notch higher so the two never cover each other — instead of docked under a file tree. */
diff --git a/src/renderer/terminal/file-links.hover-open.test.ts b/src/renderer/terminal/file-links.hover-open.test.ts
new file mode 100644
index 000000000..4bb8774cc
--- /dev/null
+++ b/src/renderer/terminal/file-links.hover-open.test.ts
@@ -0,0 +1,223 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from 'vitest'
+import type { ILink, Terminal } from '@xterm/xterm'
+import {
+ createFileLinkProvider,
+ createOsc8LinkHandler,
+ createUrlLinkProvider,
+ installLinkClickFallback,
+ type LinkHoverTarget
+} from './file-links'
+
+const COLS = 40
+const CELL_W = 10
+const CELL_H = 20
+
+/** The slice of xterm the providers and the click fallback read (see file-links.context-menu.test). */
+function fakeTerm(rows: string[], opts: { tracking?: string; selection?: boolean } = {}) {
+ const host = document.createElement('div')
+ const screen = document.createElement('div')
+ screen.className = 'xterm-screen'
+ screen.getBoundingClientRect = () =>
+ ({ left: 0, top: 0, width: COLS * CELL_W, height: rows.length * CELL_H }) as DOMRect
+ host.appendChild(screen)
+ document.body.appendChild(host)
+ let cleared = 0
+ const term = {
+ cols: COLS,
+ rows: rows.length,
+ element: host,
+ modes: { mouseTrackingMode: opts.tracking ?? 'vt200' },
+ hasSelection: () => !!opts.selection,
+ clearSelection: () => void cleared++,
+ buffer: {
+ active: {
+ viewportY: 0,
+ length: rows.length,
+ getLine: (r: number) =>
+ r < rows.length
+ ? {
+ isWrapped: false,
+ translateToString: (trim: boolean) => (trim ? rows[r].trimEnd() : rows[r].padEnd(COLS)),
+ getCell: () => ({ extended: { urlId: 0 } })
+ }
+ : undefined
+ }
+ },
+ _core: { _oscLinkService: { getLinkData: () => undefined } }
+ } as unknown as Terminal
+ return { term, host, screen, cleared: () => cleared }
+}
+
+const mouse = (o: Partial<MouseEventInit> = {}): MouseEvent => new MouseEvent('mouseup', { button: 0, ...o })
+
+const EXISTS = new Set(['/p/out/report.csv', '/p/out'])
+const lookup = async (abs: string) => ({ exists: EXISTS.has(abs), dir: abs === '/p/out' })
+
+async function fileLinks(selection = false) {
+ const { term } = fakeTerm(['wrote out/report.csv and out/ ok'], { selection })
+ const calls: string[] = []
+ const hovers: Array<LinkHoverTarget | 'leave'> = []
+ const provider = createFileLinkProvider(term, {
+ getCwd: () => '/p',
+ lookup,
+ convention: () => ({}),
+ activate: (abs, dir) => calls.push(`open ${abs} ${dir}`),
+ openWithSystem: (abs, dir) => calls.push(`system ${abs} ${dir}`),
+ hoverSink: { hover: (t) => hovers.push(t), leave: () => hovers.push('leave') }
+ })
+ const links = await new Promise<ILink[]>((resolve) =>
+ provider.provideLinks(1, (l) => resolve(l ?? []))
+ )
+ return { links, calls, hovers }
+}
+
+describe('file link provider: modifier routing', () => {
+ it('Cmd/Ctrl opens in the editor; Shift+Cmd/Ctrl opens with the OS app; a plain click does nothing', async () => {
+ const { links, calls } = await fileLinks()
+ const file = links.find((l) => l.text === 'out/report.csv')!
+ file.activate(mouse(), file.text)
+ file.activate(mouse({ shiftKey: true }), file.text)
+ expect(calls).toEqual([])
+ file.activate(mouse({ metaKey: true }), file.text)
+ file.activate(mouse({ ctrlKey: true, shiftKey: true }), file.text)
+ expect(calls).toEqual(['open /p/out/report.csv false', 'system /p/out/report.csv false'])
+ })
+
+ it('a Shift+Cmd click that extended an xterm selection is a selection, not an open', async () => {
+ const { links, calls } = await fileLinks(true)
+ links[0].activate(mouse({ metaKey: true, shiftKey: true }), links[0].text)
+ expect(calls).toEqual([])
+ })
+
+ it('without an openWithSystem, Shift+Cmd falls back to the plain open (old hosts unchanged)', async () => {
+ const { term } = fakeTerm(['wrote out/report.csv ok'])
+ const calls: string[] = []
+ const provider = createFileLinkProvider(term, {
+ getCwd: () => '/p',
+ lookup,
+ convention: () => ({}),
+ activate: (abs) => calls.push(abs)
+ })
+ const links = await new Promise<ILink[]>((r) => provider.provideLinks(1, (l) => r(l ?? [])))
+ links[0].activate(mouse({ metaKey: true, shiftKey: true }), links[0].text)
+ expect(calls).toEqual(['/p/out/report.csv'])
+ expect(links[0].hover).toBeUndefined()
+ })
+
+ it('hover names the RESOLVED path and dir-ness; leave and an open both hide it', async () => {
+ const { links, hovers } = await fileLinks()
+ const dir = links.find((l) => l.text === 'out/')
+ // `out/` alone is not a path token (no internal slash); the file is.
+ expect(dir).toBeUndefined()
+ const file = links[0]
+ file.hover!(mouse(), file.text)
+ file.leave!(mouse(), file.text)
+ file.hover!(mouse(), file.text)
+ file.activate(mouse({ metaKey: true }), file.text)
+ expect(hovers).toEqual([
+ { kind: 'file', abs: '/p/out/report.csv', dir: false },
+ 'leave',
+ { kind: 'file', abs: '/p/out/report.csv', dir: false },
+ 'leave'
+ ])
+ })
+})
+
+describe('URL links get the same tooltip', () => {
+ it('the typed-URL provider reports its URL on hover', () => {
+ const { term } = fakeTerm(['see https://example.com/docs now'])
+ const hovers: Array<LinkHoverTarget | 'leave'> = []
+ const opened: string[] = []
+ const provider = createUrlLinkProvider(term, (u) => opened.push(u), {
+ hover: (t) => hovers.push(t),
+ leave: () => hovers.push('leave')
+ })
+ let links: ILink[] = []
+ provider.provideLinks(1, (l) => (links = l ?? []))
+ links[0].hover!(mouse(), links[0].text)
+ links[0].activate(mouse({ metaKey: true, shiftKey: true }), links[0].text)
+ expect(hovers).toEqual([{ kind: 'url', url: 'https://example.com/docs' }, 'leave'])
+ expect(opened).toEqual(['https://example.com/docs'])
+ })
+
+ it('an OSC 8 link reports its hidden URL on hover, and never a non-http one', () => {
+ const hovers: Array<LinkHoverTarget | 'leave'> = []
+ const h = createOsc8LinkHandler(() => {}, {
+ hover: (t) => hovers.push(t),
+ leave: () => hovers.push('leave')
+ })
+ const range = { start: { x: 1, y: 1 }, end: { x: 2, y: 1 } }
+ h.hover!(mouse(), 'https://pr.example/1', range)
+ h.hover!(mouse(), 'javascript:alert(1)', range)
+ h.leave!(mouse(), 'https://pr.example/1', range)
+ expect(hovers).toEqual([{ kind: 'url', url: 'https://pr.example/1' }, 'leave'])
+ })
+})
+
+/** Dispatch a left-button event at buffer cell (row, col) on the screen, like a real click. */
+function fire(target: HTMLElement, type: string, row: number, col: number, mods: MouseEventInit = {}) {
+ const e = new MouseEvent(type, {
+ bubbles: true,
+ cancelable: true,
+ button: 0,
+ clientX: col * CELL_W + 2,
+ clientY: row * CELL_H + 2,
+ ...mods
+ })
+ target.dispatchEvent(e)
+ return e
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 0))
+
+describe('installLinkClickFallback (tmux mouse tracking): modifier routing', () => {
+ function setup() {
+ const t = fakeTerm(['wrote out/report.csv ok'])
+ const calls: string[] = []
+ let reached = 0
+ t.screen.addEventListener('mouseup', () => reached++)
+ installLinkClickFallback(t.term, t.host, {
+ getCwd: () => '/p',
+ lookup,
+ convention: () => ({}),
+ fileEnabled: () => true,
+ openUrl: (u) => calls.push(`url ${u}`),
+ activateFile: (abs) => calls.push(`open ${abs}`),
+ openFileWithSystem: (abs) => calls.push(`system ${abs}`)
+ })
+ return { ...t, calls, reached: () => reached }
+ }
+
+ it('Cmd opens, Shift+Cmd opens with the OS app, and both are swallowed from tmux', async () => {
+ const { screen, calls, reached } = setup()
+ fire(screen, 'mouseup', 0, 8, { metaKey: true })
+ fire(screen, 'mouseup', 0, 8, { metaKey: true, shiftKey: true })
+ await tick()
+ expect(calls).toEqual(['open /p/out/report.csv', 'system /p/out/report.csv'])
+ expect(reached()).toBe(0)
+ })
+
+ it('a plain click, and a Shift-only click, reach tmux untouched', async () => {
+ const { screen, calls, reached } = setup()
+ fire(screen, 'mouseup', 0, 8)
+ fire(screen, 'mouseup', 0, 8, { shiftKey: true })
+ await tick()
+ expect(calls).toEqual([])
+ expect(reached()).toBe(2)
+ })
+
+ it('a Shift+Ctrl DRAG that ends on a link is a selection, never an open', async () => {
+ const { screen, calls, reached } = setup()
+ fire(screen, 'mousedown', 0, 1, { ctrlKey: true, shiftKey: true })
+ fire(screen, 'mouseup', 0, 8, { ctrlKey: true, shiftKey: true })
+ await tick()
+ expect(calls).toEqual([])
+ expect(reached()).toBe(1)
+ // …while a press and release on the same cell is still a click.
+ fire(screen, 'mousedown', 0, 8, { ctrlKey: true, shiftKey: true })
+ fire(screen, 'mouseup', 0, 8, { ctrlKey: true, shiftKey: true })
+ await tick()
+ expect(calls).toEqual(['system /p/out/report.csv'])
+ })
+})
diff --git a/src/renderer/terminal/file-links.ts b/src/renderer/terminal/file-links.ts
index 8091ea52d..b1a0ef7df 100644
--- a/src/renderer/terminal/file-links.ts
+++ b/src/renderer/terminal/file-links.ts
@@ -24,6 +24,17 @@
// gated tightly and capped at MAX_JOIN_ROWS, and the regex still has to match across the
// seam for a link to result.
import type { ILink, ILinkHandler, ILinkProvider, Terminal } from '@xterm/xterm'
+import { linkOpenIntent } from './link-hover'
+
+/** What a hovered link resolved to — what the host's hover tooltip names (see link-hover.ts). */
+export type LinkHoverTarget = { kind: 'file'; abs: string; dir: boolean } | { kind: 'url'; url: string }
+
+/** The host's hover tooltip. Optional everywhere: a host without one (the kanban card modal)
+ * keeps exactly the pre-tooltip behaviour. */
+export interface LinkHoverSink {
+ hover(target: LinkHoverTarget, event: MouseEvent): void
+ leave(): void
+}
export interface FileToken {
/** The raw matched span (drives the underline range), incl. any :line:col suffix. */
@@ -191,12 +202,25 @@ function isHttpUrl(text: string): boolean {
* built-in fallback is a window.confirm). The URI is invisible text the label hides, so a
* `javascript:`/`file:` link must never reach openExternal.
*/
-export function createOsc8LinkHandler(openUrl: (url: string) => void): ILinkHandler {
+export function createOsc8LinkHandler(
+ openUrl: (url: string) => void,
+ hoverSink?: LinkHoverSink
+): ILinkHandler {
return {
activate: (event: MouseEvent, text: string): void => {
if (!(event.metaKey || event.ctrlKey)) return
+ hoverSink?.leave()
if (isHttpUrl(text)) openUrl(text)
- }
+ },
+ // The one link whose target the screen never shows — the hover is where the user learns it.
+ ...(hoverSink
+ ? {
+ hover: (event: MouseEvent, text: string): void => {
+ if (isHttpUrl(text)) hoverSink.hover({ kind: 'url', url: text }, event)
+ },
+ leave: (): void => hoverSink.leave()
+ }
+ : {})
}
}
@@ -454,6 +478,12 @@ export interface FileLinkDeps extends CwdSources {
convention?: () => PathConventionOpts | null
lookup(abs: string): Promise<PathLookup>
activate(abs: string, dir: boolean): void
+ /** Shift+Cmd/Ctrl+click: hand the path to the OS default app (the host decides per surface —
+ * see `systemOpenRefusal`). Absent = the plain `activate`, so a host that never wired it keeps
+ * its old behaviour for the Shift variant too. */
+ openWithSystem?(abs: string, dir: boolean): void
+ /** Hover tooltip naming the resolved path. */
+ hoverSink?: LinkHoverSink
}
/** The minimal buffer slice paragraph joining needs — unit tests drive a fake. */
@@ -562,14 +592,30 @@ export function createFileLinkProvider(term: Terminal, deps: FileLinkDeps): ILin
tokens.map(async (t): Promise<ILink | null> => {
const found = await findExistingPath(t.path, convention, deps)
if (!found.found) return null
- const { abs } = found
+ const { abs, dir } = found
+ const sink = deps.hoverSink
return {
text: t.text,
range: tokenRange(logical.startRow, cols, t.startIndex, t.text.length),
activate: (event: MouseEvent) => {
- if (!(event.metaKey || event.ctrlKey)) return
- deps.activate(abs, found.dir)
- }
+ const intent = linkOpenIntent(event)
+ if (intent === 'none') return
+ sink?.leave()
+ if (intent === 'system') {
+ // Shift also extends an xterm selection: a Shift+Cmd click that left one behind
+ // was a selection gesture, not an open.
+ if (term.hasSelection()) return
+ ;(deps.openWithSystem ?? deps.activate)(abs, dir)
+ return
+ }
+ deps.activate(abs, dir)
+ },
+ ...(sink
+ ? {
+ hover: (event: MouseEvent) => sink.hover({ kind: 'file', abs, dir }, event),
+ leave: () => sink.leave()
+ }
+ : {})
}
})
).then((links) => {
@@ -586,7 +632,11 @@ export function createFileLinkProvider(term: Terminal, deps: FileLinkDeps): ILin
* underlined and opened just the first row's fragment of a long OAuth URL). Modifier-gated in
* activate like the file provider, so plain clicks stay selections.
*/
-export function createUrlLinkProvider(term: Terminal, openUrl: (url: string) => void): ILinkProvider {
+export function createUrlLinkProvider(
+ term: Terminal,
+ openUrl: (url: string) => void,
+ hoverSink?: LinkHoverSink
+): ILinkProvider {
return {
provideLinks(bufferLineNumber: number, callback: (links: ILink[] | undefined) => void): void {
const logical = paragraphContaining(bufferView(term), bufferLineNumber - 1)
@@ -599,8 +649,16 @@ export function createUrlLinkProvider(term: Terminal, openUrl: (url: string) =>
text: u.text,
range: tokenRange(logical.startRow, term.cols, u.startIndex, u.text.length),
activate: (event: MouseEvent) => {
- if (event.metaKey || event.ctrlKey) openUrl(u.url)
- }
+ if (!(event.metaKey || event.ctrlKey)) return
+ hoverSink?.leave()
+ openUrl(u.url)
+ },
+ ...(hoverSink
+ ? {
+ hover: (event: MouseEvent) => hoverSink.hover({ kind: 'url', url: u.url }, event),
+ leave: () => hoverSink.leave()
+ }
+ : {})
})
)
callback(links.length ? links : undefined)
@@ -756,6 +814,8 @@ export function linkAtCell(
export interface LinkClickDeps extends LinkHitDeps {
lookup(abs: string): Promise<PathLookup>
activateFile(abs: string, dir: boolean): void
+ /** Shift+Cmd/Ctrl+click on a file — see FileLinkDeps.openWithSystem. Absent = `activateFile`. */
+ openFileWithSystem?(abs: string, dir: boolean): void
openUrl(url: string): void
/** A Cmd/Ctrl+click on a path found under neither cwd. The click is already swallowed (it
* must be, before the async lookup), so without this it would do nothing at all — the host says
@@ -772,16 +832,30 @@ export interface LinkClickDeps extends LinkHitDeps {
* ⇒ early return). This capture-phase `mouseup` listener runs BEFORE xterm's mouse handler:
* gated on the modifier, it hit-tests the buffer itself, opens the link, and stops propagation
* so the mouse report is never sent. Non-modifier clicks/drags fall through untouched, so tmux
- * copy-mode selection and scrolling are unaffected. Attach to `term.element` so the listener
- * travels with the terminal across park/adopt. Returns a disposer.
+ * copy-mode selection and scrolling are unaffected. Shift added to the modifier routes a file to
+ * `openFileWithSystem` (`linkOpenIntent`); a modified press released on another cell is a drag
+ * and is left alone. Hover is NOT this listener's job: xterm's linkifier listens to `mousemove`
+ * on its screen element whatever the mouse-tracking mode, so the providers' `hover` fires in a
+ * tmux pane too. Attach to `term.element` so the listener travels with the terminal across
+ * park/adopt. Returns a disposer.
*/
export function installLinkClickFallback(
term: Terminal,
host: HTMLElement,
deps: LinkClickDeps
): { dispose(): void } {
+ // The cell a modified press landed on. A release on a DIFFERENT cell is a drag (off-mac,
+ // Shift+Ctrl+drag is xterm's forced selection even with mouse reporting on), never a click —
+ // opening whatever link the drag happened to end on would hijack the selection.
+ let down: { row: number; col: number } | null = null
+ const onMouseDown = (ev: MouseEvent): void => {
+ down = ev.button === 0 && linkOpenIntent(ev) !== 'none' ? bufferPosFromEvent(term, ev) : null
+ }
const onMouseUp = (ev: MouseEvent): void => {
- if (ev.button !== 0 || !(ev.metaKey || ev.ctrlKey)) return
+ const pressed = down
+ down = null
+ const intent = linkOpenIntent(ev)
+ if (ev.button !== 0 || intent === 'none') return
// Only take over when the app has mouse-reporting on (tmux mouse / agent TUI) — that is the
// exact case where xterm's own link `activate` never fires. With reporting OFF (a plain shell
// when tmux is unavailable) the registered providers handle the click, so stepping in
@@ -789,6 +863,7 @@ export function installLinkClickFallback(
if (term.modes.mouseTrackingMode === 'none') return
const pos = bufferPosFromEvent(term, ev)
if (!pos) return
+ if (pressed && (pressed.row !== pos.row || pressed.col !== pos.col)) return
const hit = linkAtCell(term, pos.row, pos.col, deps)
if (!hit) return
// Swallow the click NOW so tmux never gets the mouse report. For a path, existence is async
@@ -801,14 +876,20 @@ export function installLinkClickFallback(
return
}
const convention = (deps.convention ? deps.convention() : { windows: deps.windows }) ?? {}
+ const open =
+ intent === 'system' ? (deps.openFileWithSystem ?? deps.activateFile) : deps.activateFile
void findExistingPath(hit.token, convention, deps).then((r) => {
- if (r.found) deps.activateFile(r.abs, r.dir)
+ if (r.found) open(r.abs, r.dir)
else deps.onMissing?.(hit.token, r)
})
}
+ host.addEventListener('mousedown', onMouseDown, { capture: true })
host.addEventListener('mouseup', onMouseUp, { capture: true })
return {
- dispose: () => host.removeEventListener('mouseup', onMouseUp, { capture: true })
+ dispose: () => {
+ host.removeEventListener('mousedown', onMouseDown, { capture: true })
+ host.removeEventListener('mouseup', onMouseUp, { capture: true })
+ }
}
}
diff --git a/src/renderer/terminal/link-hover.test.ts b/src/renderer/terminal/link-hover.test.ts
new file mode 100644
index 000000000..ca61a5b53
--- /dev/null
+++ b/src/renderer/terminal/link-hover.test.ts
@@ -0,0 +1,167 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+ createLinkHintTooltip,
+ fileLinkHint,
+ hideLinkHints,
+ linkOpenIntent,
+ systemOpenRefusal,
+ urlLinkHint
+} from './link-hover'
+
+const ev = (o: Partial<Record<'metaKey' | 'ctrlKey' | 'shiftKey', boolean>>) => ({
+ metaKey: false,
+ ctrlKey: false,
+ shiftKey: false,
+ ...o
+})
+
+describe('linkOpenIntent', () => {
+ it('a plain click, and Shift alone (xterm selection), are not link gestures', () => {
+ expect(linkOpenIntent(ev({}))).toBe('none')
+ expect(linkOpenIntent(ev({ shiftKey: true }))).toBe('none')
+ })
+ it('Cmd or Ctrl opens; adding Shift asks for the OS app', () => {
+ expect(linkOpenIntent(ev({ metaKey: true }))).toBe('open')
+ expect(linkOpenIntent(ev({ ctrlKey: true }))).toBe('open')
+ expect(linkOpenIntent(ev({ metaKey: true, shiftKey: true }))).toBe('system')
+ expect(linkOpenIntent(ev({ ctrlKey: true, shiftKey: true }))).toBe('system')
+ })
+})
+
+describe('fileLinkHint', () => {
+ it('mac: the resolved path plus both gestures in glyphs', () => {
+ expect(fileLinkHint({ abs: '/p/src/a.ts', dir: false, mac: true, systemOpen: true })).toBe(
+ '/p/src/a.ts (⌘-click to open · ⇧⌘-click to open with default app)'
+ )
+ })
+ it('off-mac: Ctrl and Shift+Ctrl spelled out', () => {
+ expect(fileLinkHint({ abs: '/p/src/a.ts', dir: false, mac: false, systemOpen: true })).toBe(
+ '/p/src/a.ts (Ctrl-click to open · Shift+Ctrl-click to open with default app)'
+ )
+ })
+ it('a directory is revealed, and its OS app is the file manager', () => {
+ expect(fileLinkHint({ abs: '/p/src', dir: true, mac: true, systemOpen: true })).toBe(
+ '/p/src (⌘-click to reveal · ⇧⌘-click to open in Finder)'
+ )
+ expect(fileLinkHint({ abs: '/p/src', dir: true, mac: false, systemOpen: true })).toBe(
+ '/p/src (Ctrl-click to reveal · Shift+Ctrl-click to open in file manager)'
+ )
+ })
+ it('does not advertise the OS-app gesture where it cannot work', () => {
+ expect(fileLinkHint({ abs: '/p/a.ts', dir: false, mac: true, systemOpen: false })).toBe(
+ '/p/a.ts (⌘-click to open)'
+ )
+ })
+})
+
+describe('urlLinkHint', () => {
+ it('names the URL (an OSC 8 label hides it) and the gesture', () => {
+ expect(urlLinkHint('https://x.dev/a', true)).toBe('https://x.dev/a (⌘-click to open)')
+ expect(urlLinkHint('https://x.dev/a', false)).toBe('https://x.dev/a (Ctrl-click to open)')
+ })
+})
+
+describe('systemOpenRefusal', () => {
+ it('desktop local project: allowed', () => {
+ expect(systemOpenRefusal({ browser: false, ssh: false, source: 'local' }, '/p/a.ts')).toBeNull()
+ })
+ it('SSH project: refused, pointing at the link menu download', () => {
+ const m = systemOpenRefusal({ browser: false, ssh: true, source: 'local' }, '/srv/app/a.ts')
+ expect(m).toMatch(/“a\.ts” is on the SSH host/)
+ expect(m).toMatch(/download/i)
+ })
+ it('Server Edition (browser tab): refused, never a silent inert openPath', () => {
+ const m = systemOpenRefusal({ browser: true, ssh: false, source: 'local' }, '/p/data.zip')
+ expect(m).toMatch(/“data\.zip” can only be opened .* by the desktop app/)
+ })
+ it('relay tab: refused — the path is on the peer', () => {
+ expect(systemOpenRefusal({ browser: false, ssh: false, source: 'relay' }, '/p/dir/')).toMatch(
+ /“dir” is on another machine/
+ )
+ })
+})
+
+describe('createLinkHintTooltip', () => {
+ afterEach(() => {
+ document.body.innerHTML = ''
+ vi.useRealTimers()
+ })
+
+ function host(rect: { left: number; top: number; width: number; height: number }, layoutW = rect.width) {
+ const el = document.createElement('div')
+ el.getBoundingClientRect = () => ({ ...rect, right: rect.left + rect.width, bottom: rect.top + rect.height }) as DOMRect
+ Object.defineProperty(el, 'offsetWidth', { value: layoutW })
+ Object.defineProperty(el, 'offsetHeight', { value: rect.height * (layoutW / rect.width) })
+ document.body.appendChild(el)
+ return el
+ }
+
+ it('lives inside the terminal, never takes pointer events, and shows near the pointer', () => {
+ const el = host({ left: 100, top: 50, width: 400, height: 200 })
+ const t = createLinkHintTooltip(el, 0)
+ const tip = el.querySelector('.term-link-hint') as HTMLElement
+ expect(tip).toBeTruthy()
+ expect(tip.classList.contains('xterm-hover')).toBe(true)
+ expect(tip.hidden).toBe(true)
+ t.show('/p/a.ts (⌘-click to open)', 150, 70)
+ expect(tip.hidden).toBe(false)
+ expect(tip.textContent).toBe('/p/a.ts (⌘-click to open)')
+ // 50px right / 20px down of the terminal origin, plus the offset.
+ expect(tip.style.left).toBe('62px')
+ expect(tip.style.top).toBe('38px')
+ t.hide()
+ expect(tip.hidden).toBe(true)
+ })
+
+ it('cancels the canvas zoom (a CSS transform on an ancestor)', () => {
+ // Rendered at half size: 200px on screen for a 400px-wide element.
+ const el = host({ left: 0, top: 0, width: 200, height: 100 }, 400)
+ const t = createLinkHintTooltip(el, 0)
+ t.show('x', 50, 25)
+ const tip = el.querySelector('.term-link-hint') as HTMLElement
+ expect(tip.style.left).toBe(`${100 + 12}px`)
+ expect(tip.style.top).toBe(`${50 + 18}px`)
+ })
+
+ it('waits for the hover delay, and a leave inside it shows nothing', () => {
+ vi.useFakeTimers()
+ const el = host({ left: 0, top: 0, width: 400, height: 200 })
+ const t = createLinkHintTooltip(el, 250)
+ const tip = el.querySelector('.term-link-hint') as HTMLElement
+ t.show('x', 10, 10)
+ vi.advanceTimersByTime(100)
+ t.hide()
+ vi.advanceTimersByTime(500)
+ expect(tip.hidden).toBe(true)
+ t.show('x', 10, 10)
+ vi.advanceTimersByTime(250)
+ expect(tip.hidden).toBe(false)
+ })
+
+ it('a press or a wheel on the terminal hides it; dispose removes it', () => {
+ const el = host({ left: 0, top: 0, width: 400, height: 200 })
+ const t = createLinkHintTooltip(el, 0)
+ const tip = el.querySelector('.term-link-hint') as HTMLElement
+ t.show('x', 10, 10)
+ el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }))
+ expect(tip.hidden).toBe(true)
+ t.show('x', 10, 10)
+ el.dispatchEvent(new WheelEvent('wheel', { bubbles: true }))
+ expect(tip.hidden).toBe(true)
+ t.dispose()
+ expect(el.querySelector('.term-link-hint')).toBeNull()
+ })
+
+ it('shows nothing for a detached (parked) terminal, and hideLinkHints clears a stale one', () => {
+ const el = host({ left: 0, top: 0, width: 400, height: 200 })
+ const t = createLinkHintTooltip(el, 0)
+ const tip = el.querySelector('.term-link-hint') as HTMLElement
+ t.show('x', 10, 10)
+ el.remove()
+ hideLinkHints(el)
+ expect(tip.hidden).toBe(true)
+ t.show('x', 10, 10)
+ expect(tip.hidden).toBe(true)
+ })
+})
diff --git a/src/renderer/terminal/link-hover.ts b/src/renderer/terminal/link-hover.ts
new file mode 100644
index 000000000..ac6579daa
--- /dev/null
+++ b/src/renderer/terminal/link-hover.ts
@@ -0,0 +1,188 @@
+// What a terminal link points at, said before the click — and the one extra gesture a link takes.
+//
+// Since relative paths resolve against the node's launch cwd OR the pane's live cwd (file-links.ts
+// `findExistingPath`), the text on screen no longer says which file a click will open. Hovering a
+// link therefore shows the RESOLVED target plus the gestures it takes:
+//
+// /home/me/proj/src/a.ts (⌘-click to open · ⇧⌘-click to open with default app)
+//
+// Behaviour adapted from Orca (MIT, Copyright (c) 2026 Lovecast Inc.) — its terminal-link hover
+// hint and Shift+Cmd "open with the system default app" routing; the code here is our own.
+//
+// Pure pieces (the modifier routing, the hint text, the per-surface refusal) are separate from the
+// one DOM piece (the tooltip), so every decision is unit-testable without a terminal.
+import { canUseLocalShell, type DownloadContext } from '../lib/download'
+
+/** What a modified click on a link asks for. `system` = hand it to the OS default app. */
+export type LinkOpenIntent = 'none' | 'open' | 'system'
+
+/**
+ * Modifier routing for every link click path (xterm's provider `activate` and the tmux-mode
+ * capture fallback), so the two cannot disagree. Cmd (mac) or Ctrl is the link modifier, exactly
+ * as before; adding Shift to it asks for the OS app. Shift ALONE is never a link gesture — it is
+ * xterm's force-selection / selection-extend modifier, and stays that.
+ */
+export function linkOpenIntent(ev: Pick<MouseEvent, 'metaKey' | 'ctrlKey' | 'shiftKey'>): LinkOpenIntent {
+ if (!(ev.metaKey || ev.ctrlKey)) return 'none'
+ return ev.shiftKey ? 'system' : 'open'
+}
+
+/** The link modifier as the user types it on this platform. */
+function mod(mac: boolean): string {
+ return mac ? '⌘' : 'Ctrl'
+}
+
+export interface FileHintOpts {
+ abs: string
+ dir: boolean
+ /** macOS glyphs (⌘ ⇧) vs spelled-out Ctrl/Shift. */
+ mac: boolean
+ /** Shift+modifier-click can hand the path to the OS here (`systemOpenRefusal` answered null).
+ * When it cannot, the gesture is not advertised — a hint promising a click that only toasts
+ * would be worse than no hint. */
+ systemOpen: boolean
+}
+
+/** The hover text for a file or directory link. */
+export function fileLinkHint({ abs, dir, mac, systemOpen }: FileHintOpts): string {
+ const m = mod(mac)
+ const shift = mac ? '⇧⌘' : 'Shift+Ctrl'
+ // A plain modified click on a directory reveals it in the Explorer drawer (TerminalNode's
+ // `openFile`), not an editor — say so.
+ const parts = [dir ? `${m}-click to reveal` : `${m}-click to open`]
+ if (systemOpen) {
+ parts.push(dir ? `${shift}-click to open in ${mac ? 'Finder' : 'file manager'}` : `${shift}-click to open with default app`)
+ }
+ return `${abs} (${parts.join(' · ')})`
+}
+
+/** The hover text for a URL link (typed or OSC 8 — whose target the visible label hides). */
+export function urlLinkHint(url: string, mac: boolean): string {
+ return `${url} (${mod(mac)}-click to open)`
+}
+
+function baseName(abs: string): string {
+ const trimmed = abs.replace(/[\\/]+$/, '')
+ const i = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'))
+ return (i >= 0 ? trimmed.slice(i + 1) : trimmed) || abs
+}
+
+/**
+ * Why Shift+modifier-click cannot open `abs` with the OS default app here, or null when it can.
+ * Gated on the SAME predicate as every other `shell.*` path action (`canUseLocalShell` — also the
+ * link menu's Reveal in Finder), so the surfaces cannot drift:
+ *
+ * - desktop, local project → null; the host calls `shell.openPath` (a directory opens in the
+ * OS file manager).
+ * - SSH project → refused. The OS here cannot open a path on another machine, and handing it the
+ * path would open an unrelated LOCAL file if one happened to exist there. We deliberately do
+ * NOT download-then-open: a click that silently copies a (possibly huge) file or whole folder
+ * to this machine is a side effect nobody asked for, and edits made in the local app would land
+ * on a stale copy, not the host's file. The link's right-click menu offers Download, one
+ * gesture away, and the toast says so.
+ * - Server Edition (browser tab) → refused: a browser cannot hand a host file to an OS app, and
+ * the bridge's `shell.openPath` is a documented inert stub. Not a fallback to the plain open —
+ * a modified gesture that silently does a DIFFERENT thing is harder to learn than one that says
+ * it is unavailable.
+ * - relay tab → refused: the path lives on the peer's machine.
+ */
+export function systemOpenRefusal(ctx: DownloadContext, abs: string): string | null {
+ if (canUseLocalShell(ctx)) return null
+ const name = baseName(abs)
+ if (ctx.source === 'relay') {
+ return `“${name}” is on another machine — it cannot be opened with an app on this one.`
+ }
+ if (ctx.ssh) {
+ return `“${name}” is on the SSH host — the apps on this machine cannot open it. Right-click the link to download it first.`
+ }
+ return `“${name}” can only be opened with its default app by the desktop app — a browser tab cannot hand a file to your operating system.`
+}
+
+export interface LinkHintTooltip {
+ /** Show `text` near viewport point (x, y), after the hover delay. */
+ show(text: string, clientX: number, clientY: number): void
+ hide(): void
+ dispose(): void
+}
+
+/** Gap between the pointer and the tooltip, in CSS px of the terminal's own (unscaled) space. */
+const OFFSET_X = 12
+const OFFSET_Y = 18
+const EDGE = 4
+
+/**
+ * The hover tooltip — one per xterm instance, living INSIDE `host` (the terminal's own element).
+ * Inside, not portalled to the body, so it travels with the terminal across a park (detached with
+ * it, invisible) and dies with it; the copy pill lives in the node for the same reason. The canvas
+ * zoom is a CSS transform on an ancestor, so the pointer's viewport offset is divided by the
+ * rendered/layout width ratio to land in the element's own coordinate space (the same cancellation
+ * `bufferPosFromEvent` does for cells), and the tooltip then scales with the terminal text.
+ *
+ * `pointer-events: none` + xterm's own `xterm-hover` class: it can never take a click, a wheel or a
+ * hover away from the terminal underneath (xterm's linkifier also ignores events from inside an
+ * `.xterm-hover` element, belt and braces). A press or a wheel anywhere on the terminal hides it —
+ * a click has just opened the link, and a scroll moved the text out from under it.
+ */
+export function createLinkHintTooltip(host: HTMLElement, delayMs = 250): LinkHintTooltip {
+ const doc = host.ownerDocument
+ const tip = doc.createElement('div')
+ tip.className = 'term-link-hint xterm-hover'
+ tip.setAttribute('role', 'tooltip')
+ tip.hidden = true
+ host.appendChild(tip)
+ let timer: ReturnType<typeof setTimeout> | null = null
+
+ const cancel = (): void => {
+ if (timer !== null) clearTimeout(timer)
+ timer = null
+ }
+ const hide = (): void => {
+ cancel()
+ tip.hidden = true
+ }
+ const place = (text: string, clientX: number, clientY: number): void => {
+ if (!host.isConnected) return
+ tip.textContent = text
+ tip.hidden = false
+ const rect = host.getBoundingClientRect()
+ const layoutW = host.offsetWidth || rect.width
+ const layoutH = host.offsetHeight || rect.height
+ const scale = layoutW > 0 && rect.width > 0 ? rect.width / layoutW : 1
+ const x = (clientX - rect.left) / scale
+ const y = (clientY - rect.top) / scale
+ const w = tip.offsetWidth
+ const h = tip.offsetHeight
+ const left = Math.max(EDGE, Math.min(x + OFFSET_X, layoutW - w - EDGE))
+ // Below the pointer; above it when that would leave the terminal.
+ const below = y + OFFSET_Y
+ const top = below + h + EDGE > layoutH ? Math.max(EDGE, y - h - OFFSET_Y / 2) : below
+ tip.style.left = `${left}px`
+ tip.style.top = `${top}px`
+ }
+ const onPress = (): void => hide()
+ host.addEventListener('mousedown', onPress, { capture: true })
+ host.addEventListener('wheel', onPress, { capture: true, passive: true })
+
+ return {
+ show(text, clientX, clientY) {
+ cancel()
+ if (delayMs <= 0) place(text, clientX, clientY)
+ else timer = setTimeout(() => place(text, clientX, clientY), delayMs)
+ },
+ hide,
+ dispose() {
+ hide()
+ host.removeEventListener('mousedown', onPress, { capture: true })
+ host.removeEventListener('wheel', onPress, { capture: true })
+ tip.remove()
+ }
+ }
+}
+
+/** Hide every link tooltip under `root` — for a terminal re-adopted from the park, whose
+ * tooltip may have been showing when its element was detached (no `mouseleave` fires then). */
+export function hideLinkHints(root: HTMLElement): void {
+ root.querySelectorAll<HTMLElement>('.term-link-hint').forEach((el) => {
+ el.hidden = true
+ })
+}