Skip to content

Make terminal link action defaults switchable - #14814

Open
torarnv wants to merge 4 commits into
stablyai:mainfrom
torarnv:terminal-link-fixes
Open

torarnv wants to merge 4 commits into
stablyai:mainfrom
torarnv:terminal-link-fixes

Conversation

@torarnv

@torarnv torarnv commented Aug 15, 2026

Copy link
Copy Markdown

ELI5

When you click a file link in the terminal, three things were off. The toggle that controls terminal link actions lived in the Browser settings even though it only ever affected the terminal. There was no way to flip which click does what — plain modifier-click vs. shift+modifier-click. And a file link written as an OSC 8 hyperlink
showed a hover hint about the "system browser" while the click actually opened the file in Orca. This PR moves the setting to where it belongs, adds an opt-in swap, and makes the hover text match what the click really does.

What Changed

Three commits, all on terminal file-link behavior:

  1. refactor(settings): move terminal link actions row to Terminal settings —
    The "Show terminal link actions" row (toggles terminalLinkActionPopoverEnabled) moves from the Browser pane's Link Routing section to Terminal → Terminal Interaction. Its copy moves from browser-link-routing-copy.ts into a terminal-owned terminal-link-actions-copy.ts, the deep-link target id becomes terminal-link-actions, and it leaves the Browser search index. Translation keys are unchanged, so no catalog entry moves.

  2. feat(terminal): add an opt-in file-link modifier swap — New setting terminalFileLinkModifierInverts, off by default. With it on, modifier-click (⌘ on Mac, Ctrl elsewhere) opens a terminal file link in the OS default app and shift+modifier-click opens it in Orca — the reverse of today's chords. Scope is terminal file links only; http(s) links still follow the Browser pane's openLinksInAppModifierInverts. Hover hints, the link-action popover, and the plain-click path all read the same preference, so the advertised chord matches the click. A remote path has no reachable OS default, so a system-default request there degrades to opening in Orca.

  3. fix(terminal): describe OSC 8 file targets with file hover copy — An OSC 8 hyperlink pointing at a file showed the URL hover hint ("⇧⌘+click for system browser") while the click routed through handleTerminalFileLink and opened the file in Orca. Extracts resolveOscLinkFileTarget from handleOscLink so hover and click ask one function whether a target names a file, resolved in order: Windows absolute path first (new URL("C:\path") parses with protocol c:), then non-URL text as a path, then a file: URI. Hover feeds the result to getTerminalFileLinkHoverHint, the same selector the plain file-link provider uses, and falls back to the URL hint for non-file targets. Also covers bare and Windows-path OSC 8 targets, not just file: URIs.

Why

The link-actions toggle only ever governed terminal links, so surfacing it under Browser settings was misleading. The OSC 8 hover/click mismatch meant the terminal told users one thing and did another for the same link. The modifier swap gives users who prefer opening files in their OS default app a way to make that the primary chord without losing the Orca path.

Linked Issue

Fixes #14813

Visual Proof

image image

Testing

  • I manually tested these changes locally
  • Automated tests added/updated, or explained why not below

AI Disclosure

Opus 4.8 1M high

Review

  • Security: no new IPC surface or privilege change; the modifier swap only
    reorders
    which existing open path a chord takes.
  • Cross-platform: chords use the platform check (⌘/Ctrl); OSC 8 resolution
    handles
    Windows absolute paths explicitly. Verified by tests, not a live Linux/Windows
    run.
  • Remote/SSH: a remote path has no OS default, so a system-default request
    degrades
    to opening in Orca.
  • Backwards compatibility: terminalFileLinkModifierInverts is a new optional
    setting, off by default; translation keys unchanged.
  • Performance: no hot-path change; resolveOscLinkFileTarget runs per
    hover/click.

Checklist

  • This PR is small and focused
  • I explained what changed and why (including ELI5)
  • Before/after screenshots or videos attached for UI changes, or N/A with
    reason
  • Self-reviewed for correctness, security, and performance
  • Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
  • pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will
    cover; local preferred) — pnpm build (incl. typecheck) passed locally;
    lint/test left to CI

@torarnv
torarnv requested a review from brennanb2025 as a code owner August 15, 2026 21:24
@coderabbitai

coderabbitai Bot commented Aug 15, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

Next included review available in 25 minutes.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 41eac4c4-1166-4071-bc57-59d4c35810f6

📥 Commits

Reviewing files that changed from the base of the PR and between 5bcbaff and 13ca8c6.

📒 Files selected for processing (31)
  • src/renderer/src/components/settings/BrowserPane.tsx
  • src/renderer/src/components/settings/BrowserTerminalLinkActionsSetting.tsx
  • src/renderer/src/components/settings/TerminalFileLinkModifierSetting.tsx
  • src/renderer/src/components/settings/TerminalInteractionSection.tsx
  • src/renderer/src/components/settings/TerminalLinkActionsSetting.tsx
  • src/renderer/src/components/settings/browser-link-routing-copy.ts
  • src/renderer/src/components/settings/browser-search.test.ts
  • src/renderer/src/components/settings/browser-search.ts
  • src/renderer/src/components/settings/terminal-file-link-modifier-copy.ts
  • src/renderer/src/components/settings/terminal-link-actions-copy.test.ts
  • src/renderer/src/components/settings/terminal-link-actions-copy.ts
  • src/renderer/src/components/settings/terminal-pane-appearance-search.ts
  • src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.test.tsx
  • src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.tsx
  • src/renderer/src/components/terminal-pane/issue-4631-terminal-hover-link-provider.repro.test.ts
  • src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts
  • src/renderer/src/components/terminal-pane/terminal-file-link-actions.ts
  • src/renderer/src/components/terminal-pane/terminal-file-open-routing.ts
  • src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
  • src/renderer/src/components/terminal-pane/terminal-link-open-hints.ts
  • src/renderer/src/components/terminal-pane/terminal-link-osc-url-routing.test.ts
  • src/renderer/src/components/terminal-pane/terminal-link-provider-buffer-fixtures.ts
  • src/renderer/src/components/terminal-pane/terminal-link-provider-link-detection.test.ts
  • src/renderer/src/components/terminal-pane/terminal-osc-link-hover-hint.test.ts
  • src/renderer/src/components/terminal-pane/terminal-osc-link-routing.ts
  • src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/lib/settings-navigation-types.ts
  • src/shared/constants.ts
  • src/shared/global-settings-types.ts
  • src/shared/telemetry-events.ts
📝 Walkthrough

Walkthrough

The change moves terminal link actions from Browser settings to Terminal Interaction settings. It adds a setting for inverting terminal file-link modifiers, with localized copy, defaults, typing, telemetry, and search entries. Terminal file activation, popover actions, fallback routing, and hover hints now use the inversion setting. OSC file links use shared target resolution and file-specific hints. Settings navigation and related tests now target the terminal pane.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly describes the opt-in terminal link modifier-default swap, which is a primary change in the pull request.
Description check ✅ Passed The description includes the required explanation, changes, rationale, linked issue, visual proof, testing status, review notes, and checklist.
Linked Issues check ✅ Passed The PR addresses all objectives in [#14813]: it fixes OSC 8 hover hints, moves the setting, and adds opt-in modifier swapping.
Out of Scope Changes check ✅ Passed The code changes support the linked issue through implementation, localization, navigation, routing, and focused tests without unrelated scope.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
src/renderer/src/components/settings/terminal-link-actions-copy.test.ts (1)

21-35: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Add a test for the catalog entry's dual-spelling claim.

Add a case asserting that getTerminalPaneInteractionSearchEntries() finds the Terminal Link Actions entry by 'ctrl' as well as 'cmd'. This would have caught the mismatch between the comment and the code flagged on terminal-pane-appearance-search.ts.


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e789387e-ff89-4f80-a462-de5902f60e69

📥 Commits

Reviewing files that changed from the base of the PR and between 7aaa7c6 and a90ea0b.

📒 Files selected for processing (31)
  • src/renderer/src/components/settings/BrowserPane.tsx
  • src/renderer/src/components/settings/BrowserTerminalLinkActionsSetting.tsx
  • src/renderer/src/components/settings/TerminalFileLinkModifierSetting.tsx
  • src/renderer/src/components/settings/TerminalInteractionSection.tsx
  • src/renderer/src/components/settings/TerminalLinkActionsSetting.tsx
  • src/renderer/src/components/settings/browser-link-routing-copy.ts
  • src/renderer/src/components/settings/browser-search.test.ts
  • src/renderer/src/components/settings/browser-search.ts
  • src/renderer/src/components/settings/terminal-file-link-modifier-copy.ts
  • src/renderer/src/components/settings/terminal-link-actions-copy.test.ts
  • src/renderer/src/components/settings/terminal-link-actions-copy.ts
  • src/renderer/src/components/settings/terminal-pane-appearance-search.ts
  • src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.test.tsx
  • src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.tsx
  • src/renderer/src/components/terminal-pane/issue-4631-terminal-hover-link-provider.repro.test.ts
  • src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts
  • src/renderer/src/components/terminal-pane/terminal-file-link-actions.ts
  • src/renderer/src/components/terminal-pane/terminal-file-open-routing.ts
  • src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
  • src/renderer/src/components/terminal-pane/terminal-link-open-hints.ts
  • src/renderer/src/components/terminal-pane/terminal-link-osc-url-routing.test.ts
  • src/renderer/src/components/terminal-pane/terminal-link-provider-buffer-fixtures.ts
  • src/renderer/src/components/terminal-pane/terminal-link-provider-link-detection.test.ts
  • src/renderer/src/components/terminal-pane/terminal-osc-link-hover-hint.test.ts
  • src/renderer/src/components/terminal-pane/terminal-osc-link-routing.ts
  • src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/lib/settings-navigation-types.ts
  • src/shared/constants.ts
  • src/shared/global-settings-types.ts
  • src/shared/telemetry-events.ts
💤 Files with no reviewable changes (3)
  • src/renderer/src/components/settings/BrowserTerminalLinkActionsSetting.tsx
  • src/renderer/src/components/settings/browser-link-routing-copy.ts
  • src/renderer/src/components/settings/browser-search.ts

@torarnv
torarnv force-pushed the terminal-link-fixes branch from a90ea0b to 7c72f37 Compare August 15, 2026 21:57
@torarnv

torarnv commented Aug 15, 2026

Copy link
Copy Markdown
Author

@coderabbitai review again please

@coderabbitai

coderabbitai Bot commented Aug 15, 2026 •

Copy link
Copy Markdown
Contributor

@torarnv I will review the latest changes in #14814.

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@torarnv
torarnv force-pushed the terminal-link-fixes branch from 7c72f37 to f9b6970 Compare August 15, 2026 22:07
@torarnv

torarnv commented Aug 16, 2026

Copy link
Copy Markdown
Author

The @coderabbitai summary is stale, and the documentation coverage check seems to go against the project AGENTS.md

What’s the recommended approach here?

@coderabbitai

coderabbitai Bot commented Aug 16, 2026

Copy link
Copy Markdown
Contributor
🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '== Repository instruction files =='
fd -HI '^AGENTS\.md$|^\.coderabbit\.ya?ml$|^coderabbit\.ya?ml$' . -E .git -E node_modules

printf '%s\n' '== AGENTS.md content =='
while IFS= read -r file; do
  printf '\n--- %s ---\n' "$file"
  cat "$file"
done < <(fd -HI '^AGENTS\.md$' . -E .git -E node_modules)

printf '%s\n' '== Documentation coverage references =='
rg -n -i -C 3 'documentation.{0,20}(coverage|threshold)|doc(umentation)?[-_ ]?coverage|docstring.{0,20}(coverage|threshold)|typedoc|api extractor' \
  -g '!node_modules/**' -g '!dist/**' -g '!build/**' .

printf '%s\n' '== CI workflow files and relevant lines =='
fd -HI .github . -t f -E .git -E node_modules 2>/dev/null | \
  rg '(^|/)(workflows/.*\.(ya?ml)|.*(ci|test|check).*\.(ya?ml))$' | \
  while IFS= read -r file; do
    printf '\n--- %s ---\n' "$file"
    rg -n -i -C 2 'doc|coverage|comment|lint|test' "$file" || true
  done

Length of output: 1421


⚙️ CodeRabbit configuration inspected

Length of output: 5387


@torarnv The recommended approach is to disable CodeRabbit’s docstring enforcement for this repository.

The active configuration enables both of these checks:

  • reviews.finishing_touches.docstrings.enabled: true
  • reviews.pre_merge_checks.docstrings.mode: warning with threshold: 80

That policy conflicts with the AGENTS.md guidance. The guidance prefers short comments that explain non-obvious rationale. It rejects redundant comments or docstrings added only to satisfy coverage.

Use this configuration:

reviews:
  finishing_touches:
    docstrings:
      enabled: false
  pre_merge_checks:
    docstrings:
      mode: off

Keep unit-test and normal review checks enabled. This change only stops generic docstring coverage warnings and docstring-generation suggestions.

The PR summary is a separate problem. Regenerate it now so it reflects the current terminal-link settings, modifier inversion, and OSC 8 hover behavior. The current configuration has high_level_summary: false, so do not rely on automatic summary updates unless that feature is enabled later.

I used the repository AGENTS.md guidance already available in the review context for this recommendation.


🧠 Learnings used
Learnt from: gatsby74
Repo: stablyai/orca PR: 0
File: :0-0
Timestamp: 2026-07-18T18:22:51.775Z
Learning: In this repository, `AGENTS.md` directs contributors to use short comments that explain non-obvious rationale and to avoid comments that merely restate code behavior; documentation coverage thresholds should not be met by adding redundant implementation descriptions.

Learnt from: gatsby74
Repo: stablyai/orca PR: 0
File: :0-0
Timestamp: 2026-06-30T14:07:16.238Z
Learning: In this repository, `AGENTS.md` prefers brief “why” comments over exhaustive docstrings. During reviews, avoid pushing blanket docstring additions purely to satisfy docstring coverage thresholds, especially for internal or JSX/helper functions, unless the change clearly improves maintainability or public API clarity.
✅ Action performed

Summary regeneration triggered.

@coderabbitai

coderabbitai Bot commented Aug 18, 2026

Copy link
Copy Markdown
Contributor

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/renderer/src/components/settings/terminal-link-actions-copy.test.ts (1)

28-34: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for the new terminal file-link modifier row.

This suite tests only getTerminalLinkActions.... It does not test getTerminalFileLinkModifierDescription or the corresponding Terminal Interaction search entry. Add Mac/non-Mac interpolation assertions and a search-entry assertion for the intended cmd and ctrl aliases. Otherwise, regressions in the new setting can pass the suite.


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 257d8d21-ab5c-42a3-9bdf-dd40b7a4ac59

📥 Commits

Reviewing files that changed from the base of the PR and between 1be6a03 and 3b2a0db841978b77e2b8e62bc221e5c3a60039b4.

📒 Files selected for processing (31)
  • src/renderer/src/components/settings/BrowserPane.tsx
  • src/renderer/src/components/settings/BrowserTerminalLinkActionsSetting.tsx
  • src/renderer/src/components/settings/TerminalFileLinkModifierSetting.tsx
  • src/renderer/src/components/settings/TerminalInteractionSection.tsx
  • src/renderer/src/components/settings/TerminalLinkActionsSetting.tsx
  • src/renderer/src/components/settings/browser-link-routing-copy.ts
  • src/renderer/src/components/settings/browser-search.test.ts
  • src/renderer/src/components/settings/browser-search.ts
  • src/renderer/src/components/settings/terminal-file-link-modifier-copy.ts
  • src/renderer/src/components/settings/terminal-link-actions-copy.test.ts
  • src/renderer/src/components/settings/terminal-link-actions-copy.ts
  • src/renderer/src/components/settings/terminal-pane-appearance-search.ts
  • src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.test.tsx
  • src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.tsx
  • src/renderer/src/components/terminal-pane/issue-4631-terminal-hover-link-provider.repro.test.ts
  • src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts
  • src/renderer/src/components/terminal-pane/terminal-file-link-actions.ts
  • src/renderer/src/components/terminal-pane/terminal-file-open-routing.ts
  • src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
  • src/renderer/src/components/terminal-pane/terminal-link-open-hints.ts
  • src/renderer/src/components/terminal-pane/terminal-link-osc-url-routing.test.ts
  • src/renderer/src/components/terminal-pane/terminal-link-provider-buffer-fixtures.ts
  • src/renderer/src/components/terminal-pane/terminal-link-provider-link-detection.test.ts
  • src/renderer/src/components/terminal-pane/terminal-osc-link-hover-hint.test.ts
  • src/renderer/src/components/terminal-pane/terminal-osc-link-routing.ts
  • src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/lib/settings-navigation-types.ts
  • src/shared/constants.ts
  • src/shared/global-settings-types.ts
  • src/shared/telemetry-events.ts
💤 Files with no reviewable changes (3)
  • src/renderer/src/components/settings/browser-search.ts
  • src/renderer/src/components/settings/BrowserTerminalLinkActionsSetting.tsx
  • src/renderer/src/components/settings/browser-link-routing-copy.ts
🚧 Files skipped from review as they are similar to previous changes (26)
  • src/renderer/src/components/settings/TerminalInteractionSection.tsx
  • src/shared/telemetry-events.ts
  • src/shared/constants.ts
  • src/renderer/src/components/terminal-pane/terminal-link-osc-url-routing.test.ts
  • src/renderer/src/components/settings/terminal-pane-appearance-search.ts
  • src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.tsx
  • src/renderer/src/components/terminal-pane/terminal-file-link-actions.ts
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/components/settings/terminal-link-actions-copy.ts
  • src/renderer/src/components/terminal-pane/terminal-link-provider-buffer-fixtures.ts
  • src/renderer/src/components/settings/browser-search.test.ts
  • src/renderer/src/lib/settings-navigation-types.ts
  • src/renderer/src/components/terminal-pane/TerminalLinkActionPopover.test.tsx
  • src/renderer/src/components/terminal-pane/terminal-file-open-routing.ts
  • src/renderer/src/components/settings/TerminalFileLinkModifierSetting.tsx
  • src/renderer/src/components/terminal-pane/issue-4631-terminal-hover-link-provider.repro.test.ts
  • src/shared/global-settings-types.ts
  • src/renderer/src/components/terminal-pane/terminal-osc-link-hover-hint.test.ts
  • src/renderer/src/components/terminal-pane/terminal-file-link-actions.test.ts
  • src/renderer/src/components/settings/TerminalLinkActionsSetting.tsx
  • src/renderer/src/components/terminal-pane/use-terminal-pane-lifecycle.ts
  • src/renderer/src/components/settings/BrowserPane.tsx
  • src/renderer/src/components/terminal-pane/terminal-link-provider-link-detection.test.ts
  • src/renderer/src/components/terminal-pane/terminal-link-handlers.ts
  • src/renderer/src/components/terminal-pane/terminal-link-open-hints.ts
  • src/renderer/src/components/terminal-pane/terminal-osc-link-routing.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

@nwparker nwparker removed the P2 label Aug 19, 2026
torarnv and others added 4 commits August 23, 2026 15:35
The "Show terminal link actions" row toggles terminalLinkActionPopoverEnabled,
which has only ever governed terminal links, but it rendered in the Browser
pane nested under Link Routing. Render it in Terminal -> Terminal Interaction
instead.

The copy moves out of browser-link-routing-copy.ts into a terminal-owned
terminal-link-actions-copy.ts, the deep-link target id becomes
terminal-link-actions, and the row leaves the Browser search index, which
shifts the positional indices BrowserPane.tsx uses to gate later rows.
Translation keys stay as they are so no catalog entry moves.
New setting terminalFileLinkModifierInverts, off by default. With it on,
Cmd-click opens a terminal file link in the OS default app and Shift+Cmd-click
opens it in Orca, the reverse of the current chords. Ctrl stands in for Cmd on
Windows and Linux.

The swap covers terminal file links only. http(s) links in the terminal keep
following the Browser pane openLinksInAppModifierInverts setting, and the
hover hints, the link-action popover, and the plain-click path all read the
same preference so the chord they advertise matches what the click does.

A remote path has no reachable OS default, so a system-default request there
degrades to opening in Orca rather than doing nothing.
An OSC 8 hyperlink pointing at a file showed the URL hover hint — "⇧⌘+click for
system browser" — while clicking it routed through handleTerminalFileLink and
opened the file in Orca. Hover and click read the same target and disagreed,
because only the click parsed it: linkHandler.hover called getUrlOpenLinkHint
unconditionally.

Extract resolveOscLinkFileTarget from handleOscLink so both surfaces ask one
function whether a target names a file, in the order that matters: a Windows
absolute path first, since new URL("C:\path\file.ts") parses with protocol c:,
then non-URL text as a path, then a file: URI. The hover feeds the result to
getTerminalFileLinkHoverHint, the same selector the plain file-link provider
uses, and falls back to the URL hint for non-file targets.

Also fixes OSC 8 targets that are bare or Windows paths rather than file: URIs,
which had the same mismatch.
The settings-search catalog and the rendered row kept two hand-maintained
keyword lists, so "invert"/"swap"/"finder" only matched the row and never the
search index. Both now read one exported helper, and each link row indexes both
platform chords so users find it by the modifier they actually type.
@nwparker
nwparker force-pushed the terminal-link-fixes branch from 3b2a0db to 13ca8c6 Compare August 24, 2026 00:38
@nwparker

Copy link
Copy Markdown
Contributor

Readiness report — rebased, gates green, validated on real Windows Electron

Head is now 13ca8c6a4363552b32e37432c72bc4637b64050f, force-pushed over 3b2a0db8419 with an exact lease and rebased onto origin/main at ab3b1d07cd6.

What changed since the last push

One new commit on top of the three existing ones:

fix(settings): share the file-link modifier search keywords — the settings-search catalog and the rendered row kept two hand-maintained keyword lists, so invert / swap / default app / finder matched only the row and never the search index. Both now read one exported getTerminalFileLinkModifierSearchKeywords(), and each terminal link row indexes both platform chords (cmd and ctrl) so a user finds the row by the modifier they actually type, not the one their OS happens to use. Five files, plus test coverage.

Gates (local, macOS)

Gate Result
pnpm lint exit 0
pnpm typecheck exit 0
pnpm build exit 0
Focused vitest (8 suites) 70 passed

Focused suites: terminal-link-actions-copy, browser-search, terminal-file-link-actions, terminal-osc-link-hover-hint, terminal-link-osc-url-routing, TerminalLinkActionPopover, terminal-link-provider-link-detection, issue-4631-terminal-hover-link-provider.repro.

Windows validation — real Electron, real clicks

Built this branch on a Windows 11 x64 box, launched the Electron dev app there, and drove it over CDP with genuine held-modifier mouse input (keyboard.down('Control') → mouse.down/up → keyboard.up), not synthetic click({modifiers}). Every screenshot below is a full, uncropped app window.

Hover copy — all Windows chords, no ⌘/Finder leakage. Tooltip text read straight out of the live .pane-link-tooltip DOM node:

Link kind Tooltip
Local file (sample.ts) … (Click for actions, Ctrl+click to open, or Shift+Ctrl+click for default app)
Local HTML (page.html) … (Click for actions, Ctrl+click to open, or Shift+Ctrl+click for default browser)
Known worktree root … (Click for actions, Ctrl+click to switch workspace, or Shift+Ctrl+click to open folder)
Plain directory (not a worktree) … (Click for actions, Ctrl+click to open, or Shift+Ctrl+click for default app)
OSC 8 target naming a file file:///C:/…/sample.ts (Click for actions, Ctrl+click to open, or Shift+Ctrl+click for default app)

That last row is the fix in fix(terminal): describe OSC 8 file targets with file hover copy — before it, an OSC 8 file:// target advertised URL copy ("system browser") while the click routed into Orca.

10-hover-file-ts.png
11-hover-file-html.png
12-hover-worktree-root.png
30-hover-osc8-file.png

Click behaviour — default (modifier not inverted):

Gesture Target Observed
Plain click sample.ts Action popover, key caps read Ctrl + Click / Shift + Ctrl + Click
Ctrl+click sample.ts Opened in the Orca editor
Shift+Ctrl+click sample.txt Launched the OS default app — Notepad window titled sample.txt - Notepad
Ctrl+click page.html Orca browser tab at file:///C:/…/page.html
Shift+Ctrl+click page.html Default browser — Edge title changed to page.html and 17 more pages
Shift+Ctrl+click worktree root File Explorer opened; Shell.Application reports LocationURL = file:///C:/…/orchestration-dogfood-20260724

41-ctrlclick-ts-opened.png
50-ctrlclick-ts.png
80-ctrlclick-html.png
92-shiftctrl-folder.png

Aside worth knowing: Shift+Ctrl+click on a .ts file spawned Microsoft.Media.Player.exe and smartscreen.exe, because Windows registers .ts as an MPEG-2 transport stream. That is the OS association doing exactly what it should — it just makes .ts a poor demo file, so the table above uses .txt.

Click behaviour — modifier inverted. Toggled through the real Settings UI, then re-measured:

Link kind Inverted tooltip
File … (Click for actions, Ctrl+click for default app, or Shift+Ctrl+click to open in Orca)
Worktree root … (Click for actions, Ctrl+click to open folder, or Shift+Ctrl+click to switch workspace)

…and the clicks follow the copy: Ctrl+click on sample.txt launched Notepad, Shift+Ctrl+click opened it in the Orca editor.

B0-hover-inverted-txt.png
B2-inverted-shiftctrl-orca.png

The search fix, in the app. Typing invert into Settings search now surfaces Terminal → Hold Shift to open files in Orca. Before this commit the catalog entry carried only terminal / file / link / shift / modifier, so this query returned nothing.

A1-settings-search-invert.png

SSH boundary — partially verified, one gap I could not close

Registered a real SSH target from the Windows app to a Linux host, connected (status: connected, remotePlatform: linux), and imported a remote folder as a project. The live Windows renderer resolves that worktree to repoConnectionId: "ssh-1787530482866-ltsy7h", which is the sole input to shouldOpenTerminalFileWithSystemDefault — so the branch that drops the system-default alternate and pins Orca as primary is reached for real on Windows.

I could not render the remote hover string, because that host cannot spawn remote PTYs at all:

Remote terminals are unavailable: node-pty's native binding is not loadable on this host.

The host has make, gcc, g++ and python3, and runs Node v26.1.0; ~/.orca-relay contains no .node binding. That is a relay-provisioning/ABI problem unrelated to this PR, and fixing it would have meant reconfiguring a shared box. So the SSH row is: boundary input proven live on Windows, rendered remote tooltip not proven live. The behaviour itself stays covered by the two unit tests in terminal-file-link-actions.test.ts that pin canOpenWithSystemDefault = false — Orca stays primary and no impossible remote alternate is offered — and the logic is platform-independent; only the chord string differs per platform, and that string is proven above on Windows for every other link kind.

C0-ssh-pane.png

All Windows test state was reverted: invert toggled back off, SSH target and imported project removed, fixture files deleted.

@nwparker

Copy link
Copy Markdown
Contributor

External CI status at time of writing

Workflows were approved for the fork and are now queued against 13ca8c6a436 — three gate jobs reporting pending, with the heavier suites not yet scheduled (they hang off detect code-relevant changes):

GitHub reports mergeable: MERGEABLE, mergeStateStatus: UNSTABLE — the "unstable" is purely the unfinished check run, not a conflict. Nothing is blocked on this end; the branch is rebased on ab3b1d07cd6 and pnpm lint, pnpm typecheck, pnpm build and the focused vitest suites all pass locally.

Windows test state on the validation host has been fully reverted: modifier-invert toggled back off, the SSH target and imported remote project removed, fixture files and driver scripts deleted, remote key access revoked, and the dev Electron instance shut down.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Terminal file-link hints and settings are inconsistent

4 participants