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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
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.mdindex 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 beshut. The kanban card modal gets URL rows only (no file links there) and no "Open in canvasbrowser" (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 fordiff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsxindex 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()+ }+ : undefinedterm.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.cssindex 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 — onenotch 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.tsnew file mode 100644index 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.tsindex 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 | nulllookup(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): ILintokens.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.hoverSinkreturn {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): voidopenUrl(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') returnconst pos = bufferPosFromEvent(term, ev)if (!pos) return+ if (pressed && (pressed.row !== pos.row || pressed.col !== pos.col)) returnconst 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.activateFilevoid 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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+ })+}