Skip to content

Add Previous/Next change navigation buttons to the Diff View - #6668

Merged
brennanb2025 merged 6 commits into
mainfrom
brennanb2025/issue-6215-diff-nav-buttons
Jul 12, 2026
Merged

brennanb2025 merged 6 commits into
mainfrom
brennanb2025/issue-6215-diff-nav-buttons

Conversation

@brennanb2025

@brennanb2025 brennanb2025 commented Jun 28, 2026 •

Copy link
Copy Markdown
Contributor

What changes

Adds Previous change (↑) and Next change (↓) buttons to the single-file Diff View toolbar (the editor header, next to the side-by-side toggle). Clicking them jumps the viewport from one change region (hunk) to the next/previous within the file — cyclic at the ends — so you no longer have to scroll to find each change. Inspired by IntelliJ/Android Studio.

What does not change: This is scoped to the single-file diff surface (diff tabs and the per-file "Changes" view). The multi-file/combined diff viewer is intentionally untouched — the buttons do not render there. No keyboard shortcut, setting, or diff-rendering behavior changes. Buttons are disabled when the file has no changes.

Closes #6215

Design approach

The Monaco diff editor instance lives in DiffViewer, while the toolbar lives in a sibling EditorPanelHeader, three levels up the tree. Rather than prop-drill a ref and a re-render signal through every intermediate (markdown/CSV/image) branch, a small instance-scoped DiffNavigationProvider (one per editor pane, mounted in EditorPanelInner) bridges the two:

  • DiffViewer calls registerDiffEditor(editor) on mount and unregisterDiffEditor(editor) on dispose / large-diff fallback.
  • The provider holds the editor in a ref and changeCount in React state, recomputed from editor.getLineChanges() on register and on Monaco's onDidUpdateDiff.
  • The buttons call Monaco's goToDiff('previous'|'next') and are disabled when changeCount === 0.

An identity guard on register/unregister (and the update callback) handles the fast tab-swap race so a stale dispose can't wipe a freshly-registered editor. Buttons reuse the existing header <button> + Tooltip pattern and lucide-react ChevronUp/ChevronDown; strings go through the i18n catalog with aria-labels on the icon-only buttons.

Design review

Ran the design doc through an automated design-review loop (Claude + Codex reviewers, 2 rounds) until clean (READY). Findings folded in: identity-carrying unregister contract (the original bare-null signature made the fast-swap guard unimplementable), explicit "changeCount must be state, not a ref" reasoning, single-subscription ownership, and a corrected precedent reference (tab-group/tab-drag-context.tsx). Scope stayed on the single-file surface throughout.

Implementation & deviations

Files: new diff-navigation-context.tsx (+ test), and edits to DiffViewer.tsx, EditorPanel.tsx, EditorPanelHeader.tsx, plus i18n catalog entries in all five locales. No deviations from the reviewed design.

Completeness verification

A read-only verification pass checked the implementation against every requirement and edge case in the design doc: COMPLETE, no omissions. (Non-English locales carry the English fallback string — the expected output of the catalog sync; real translation is a downstream step.)

Headline behavior status

Implemented — and confirmed running in the real app (not fixture-only). The buttons call goToDiff on the live Monaco editor registered from DiffViewer's production mount path; changeCount from getLineChanges() drives the enabled state.

Perf audit

Touched hot paths: the new provider, EditorPanel's wrap, and DiffViewer's register/unregister. Audit result: clean, no fixes needed. Key point — changeCount flips do not re-render Monaco/EditorContent: the children element reference is preserved across the provider's own re-render, so only the two context consumers (header + DiffViewer wrapper) re-render, and only on infrequent diff-recompute events (not per keystroke/scroll). The onDidUpdateDiff subscription is bounded to one per provider and disposed on unregister/re-register/unmount; no editor retention or leak. Type-only Monaco import, so no startup cost. Coverage is via the deterministic unit test below rather than a benchmark.

Code review

Ran an iterative review loop, then re-ran two independent reviewers in parallel focused on (1) lifecycle/disposal/provider-scoping and (2) button render/gating/i18n/accessibility. Both returned no CONFIRMED bugs. They verified: per-pane provider isolation (no cross-split bleed), the fast-swap identity guard holds, single bounded subscription with full disposal, correct i18n hash keys with matching tooltip + aria-label, correct combined-diff exclusion (double-gated), and correct icon→direction wiring. The one PLAUSIBLE-but-unreachable note (Monaco goToDiff on a disposed editor) is guarded because every count-clearing path disables the buttons first.

Manual validation (brennan-test-changes)

Validated on the real Electron surface (verdict: LAND). Tested on a throwaway repo with a 3-hunk file:

  • Buttons appear in the diff header next to the side-by-side toggle, enabled, with 3 change regions present.
  • Next advanced the Monaco modified-pane cursor through each region (top px: 40 → 220 → 400) and wrapped back to the first (→ 40); Previous moved backward and wrapped. Proven via before/after cursor position, not just clicks.
  • Buttons disabled (greyed, opacity 0.5) on an empty staged diff (0 changes).
  • Buttons absent on the combined multi-file "Changes" viewer (scope boundary holds).

Screenshots showing the buttons in the header, the disabled state, and their absence on the combined viewer are attached in a follow-up comment.

Static checks & tests

  • typecheck:web (tsgo): clean
  • oxlint on touched files / editor dir: clean
  • verify:localization-catalog: clean (both new keys present, parity across es/ja/ko/zh)
  • New unit test diff-navigation-context.test.tsx (3 cases: nav routing + goToDiff; 0→N onDidUpdateDiff re-render proving count is state; stale-unregister identity-guard no-op) plus existing ChangesModeView / EditorContent tests: 7 passing

Cross-platform / SSH

Renderer-only UI on the already-mounted Monaco diff editor — no IPC, no filesystem, no platform branches, no keyboard shortcut. Works identically for local and SSH-backed worktrees. Icons from the existing lucide-react dependency.

Assumptions / remaining risk

  • The per-file "Changes" mode (edit-mode file toggled to Changes view) shares the identical provider/shell/DiffViewer wiring as the single-file diff that was fully exercised, so it's covered by construction rather than a separate manual pass.
  • Non-actionable: the second onDidUpdateDiff listener coexists with DiffViewer's pre-existing auto-scroll listener; both are low-frequency, left separate for clean ownership.

Made with Orca 🐋

Add up/down navigation buttons to the single-file Diff View toolbar so
users can jump between change regions (hunks) without scrolling, matching
IntelliJ/Android Studio. The buttons bridge the Monaco diff editor to the
header via an instance-scoped DiffNavigationProvider and call Monaco's
goToDiff('previous'|'next'); they disable when the file has no changes.

Closes #6215

Co-authored-by: Orca <help@stably.ai>
@brennanb2025

Copy link
Copy Markdown
Contributor Author

Manual validation evidence (Electron)

Validated on the real Orca dev build (this branch's worktree) against a throwaway repo whose sample.ts has 3 distinct change regions. Backing state was read from the live Monaco modified editor (cursor top in px) to prove the viewport actually moved, not just that clicks fired.

State What it shows
Diff open, buttons enabled The ↑/↓ buttons render in the editor header between the side-by-side toggle and the ⋯ menu; file has 3 change regions.
After Next ×N Modified-pane cursor advanced 40 → 220 → 400 px through the three regions, then wrapped back to 40 px (cyclic). Previous moved backward and wrapped.
Empty staged diff Both buttons disabled (greyed, opacity 0.5) when there are 0 changes.
Combined multi-file "Changes" viewer Buttons are absent — the feature is scoped to the single-file surface only.

Verdict from the validation pass: LAND. Static checks (typecheck, oxlint, localization catalog) pass; 7 unit/component tests pass.

Screenshots demonstrating each state were captured during validation; I can drag them into this thread on request (image upload isn't available from my automation path).

@coderabbitai

coderabbitai Bot commented Jun 28, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: e208f4c8-f576-4985-a4c0-85a044933b1f

📥 Commits

Reviewing files that changed from the base of the PR and between 404fffe and 57bc540.

📒 Files selected for processing (1)
  • src/renderer/src/components/editor/diff-navigation-context.test.tsx
🚧 Files skipped from review as they are similar to previous changes (1)
  • src/renderer/src/components/editor/diff-navigation-context.test.tsx

📝 Walkthrough

Walkthrough

A new diff-navigation-context.tsx module introduces DiffNavigationProvider, useDiffNavigation, and DiffNavigationContextValue. The provider tracks one active Monaco diff editor, subscribes to onDidUpdateDiff to maintain changeCount, and exposes previous/next navigation actions. EditorPanel wraps its shell in the provider. DiffViewer registers and unregisters its editor on mount, dispose, and large-diff fallback transitions. EditorPanelHeader adds previous/next change buttons wired to the context, disabled when changeCount === 0. Five locale files add the new navigation labels.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.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 matches the main user-visible change: adding previous/next change navigation buttons to the diff view.
Description check ✅ Passed The description is detailed and covers summary, testing, review, and notes, but it does not follow the template exactly and omits a dedicated security audit section.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

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.

🧹 Nitpick comments (1)
src/renderer/src/components/editor/diff-navigation-context.test.tsx (1)

24-27: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Cover the stale onDidUpdateDiff callback path too.

This suite verifies the stale unregisterDiffEditor guard, but it never proves that an update from oldEditor is ignored after newEditor takes over. A regression in the provider's fast-swap update guard would still pass here and could flip changeCount back to a stale value in the header. Consider making dispose clear the stored callback and adding an assertion like oldEditor.fireUpdate() leaves captured?.changeCount at 4.

Suggested test adjustment
 function createFakeEditor(initialCount: number): FakeDiffEditor {
   let count = initialCount
   let updateCallback: (() => void) | null = null
   const editor = {
     getLineChanges: () => (count > 0 ? Array.from({ length: count }, () => ({})) : []),
     goToDiff: vi.fn(),
     onDidUpdateDiff: (cb: () => void) => {
       updateCallback = cb
-      return { dispose: () => {} }
+      return {
+        dispose: () => {
+          updateCallback = null
+        }
+      }
     },
     setLineChanges: (next: number) => {
       count = next
     },
     fireUpdate: () => updateCallback?.()
   } as unknown as FakeDiffEditor
   return editor
 }
   it('ignores a stale unregister for an editor that is no longer current (identity guard)', () => {
     mount()
     const oldEditor = createFakeEditor(1)
     const newEditor = createFakeEditor(4)

     // Fast-swap: new editor registers before the old one's dispose fires.
     act(() => captured?.registerDiffEditor(oldEditor))
     act(() => captured?.registerDiffEditor(newEditor))
     expect(captured?.changeCount).toBe(4)

+    act(() => {
+      oldEditor.setLineChanges(9)
+      oldEditor.fireUpdate()
+    })
+    expect(captured?.changeCount).toBe(4)
+
     act(() => captured?.unregisterDiffEditor(oldEditor))

     // New editor's count is intact and nav still routes to it.
     expect(captured?.changeCount).toBe(4)

Also applies to: 97-114


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: da87b2de-859c-44c7-ad6f-6ead4b79e5a8

📥 Commits

Reviewing files that changed from the base of the PR and between 2e59e06 and 404fffe.

📒 Files selected for processing (10)
  • src/renderer/src/components/editor/DiffViewer.tsx
  • src/renderer/src/components/editor/EditorPanel.tsx
  • src/renderer/src/components/editor/EditorPanelHeader.tsx
  • src/renderer/src/components/editor/diff-navigation-context.test.tsx
  • src/renderer/src/components/editor/diff-navigation-context.tsx
  • src/renderer/src/i18n/locales/en.json
  • src/renderer/src/i18n/locales/es.json
  • src/renderer/src/i18n/locales/ja.json
  • src/renderer/src/i18n/locales/ko.json
  • src/renderer/src/i18n/locales/zh.json

Address CodeRabbit nitpick: prove that an update fired from a replaced
editor is ignored after a new editor registers (the subscription is
disposed on re-register). The fake editor's dispose now clears its
callback, matching real Monaco subscription semantics.

Co-authored-by: Orca <help@stably.ai>
@brennanb2025

Copy link
Copy Markdown
Contributor Author

Addressed the nitpick in 57bc540 — the fake editor's dispose now clears its callback (matching real Monaco subscription semantics), and the fast-swap test asserts a stale onDidUpdateDiff from the replaced editor leaves changeCount unchanged. This proves both that re-register disposes the prior subscription and that the update callback's current-editor guard holds.

Brennan Benson added 2 commits July 10, 2026 17:34
# Conflicts:
#	src/renderer/src/components/editor/EditorPanel.tsx
#	src/renderer/src/i18n/locales/es.json
@sonhyrd

sonhyrd commented Jul 11, 2026 •

Copy link
Copy Markdown
Contributor

This really nice to push

The main thing I noticed is it's mouse-only. The commenter on #6215 asked for F7/Shift+F7 specifically, which is what VS Code and JetBrains do by default. Your goToDiff wiring made it easy to build on, so I put up a follow-up stacked on this branch (#8240) that adds the keyboard shortcuts through the same provider — plus it translates the Previous/Next change strings (still English in es/ja/ko/zh) and shows the shortcut in the button tooltips. It's based off this branch, so this one needs to land first.

Couple of small things, not blockers:

  • the three separate TooltipProviders could collapse into one
  • the provider wraps every file type in EditorPanel, not just diffs — harmless since it no-ops, just a bit wider than it needs to be

@brennanb2025
brennanb2025 merged commit b93ec86 into main Jul 12, 2026
2 checks passed
@brennanb2025

Copy link
Copy Markdown
Contributor Author

Thanks—this is a great follow-up. I agree F7/Shift+F7 is the right keyboard behavior, and keeping it rebindable through the existing keybinding system sounds ideal. #6668 is merged now, so I’m reviewing #8240 next and will retarget it to main as part of that pass.

Also noted on the TooltipProvider consolidation and provider scope. I’m moving the TooltipProvider DRY cleanup into a focused follow-up so it doesn’t muddy the keyboard/i18n review.

brennanb2025 pushed a commit to sonhyrd/orca that referenced this pull request Jul 12, 2026
Stacks on the Previous/Next change buttons (stablyai#6668) to add keyboard
navigation for single-file diffs, matching VS Code / JetBrains diff review.

- Register editor.nextChange (F7) / editor.previousChange (Shift+F7) in the
  keybinding registry (Editors group) so they show in Settings and stay
  rebindable.
- Teach the keybinding normalizer function keys (F1-F24) and make them
  first-class in the bare-key safety model (safe standalone or with Shift,
  opt-in per action) - F7 was previously unbindable.
- Install a capture-phase listener from DiffNavigationProvider so keyboard
  and the existing header buttons share one goToDiff path; works on
  read-only and editable single-file diffs.
- Translate the Previous/Next change strings for es/ja/ko/zh.

Refs stablyai#6215
brennanb2025 pushed a commit that referenced this pull request Jul 12, 2026
* feat(diff): add F7/Shift+F7 keyboard navigation for diff changes

Stacks on the Previous/Next change buttons (#6668) to add keyboard
navigation for single-file diffs, matching VS Code / JetBrains diff review.

- Register editor.nextChange (F7) / editor.previousChange (Shift+F7) in the
  keybinding registry (Editors group) so they show in Settings and stay
  rebindable.
- Teach the keybinding normalizer function keys (F1-F24) and make them
  first-class in the bare-key safety model (safe standalone or with Shift,
  opt-in per action) - F7 was previously unbindable.
- Install a capture-phase listener from DiffNavigationProvider so keyboard
  and the existing header buttons share one goToDiff path; works on
  read-only and editable single-file diffs.
- Translate the Previous/Next change strings for es/ja/ko/zh.

Refs #6215

* test(diff): cover change navigation shortcuts

* fix(diff): use shortcut chips in navigation tooltips

---------

Co-authored-by: Brennan Benson <brennanbenson@Brennans-MacBook-Pro.local>
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
…i#6668)

* feat(diff): add Previous/Next change navigation buttons to Diff View

Add up/down navigation buttons to the single-file Diff View toolbar so
users can jump between change regions (hunks) without scrolling, matching
IntelliJ/Android Studio. The buttons bridge the Monaco diff editor to the
header via an instance-scoped DiffNavigationProvider and call Monaco's
goToDiff('previous'|'next'); they disable when the file has no changes.

Closes stablyai#6215

Co-authored-by: Orca <help@stably.ai>

* test(diff): cover stale onDidUpdateDiff guard in fast-swap

Address CodeRabbit nitpick: prove that an update fired from a replaced
editor is ignored after a new editor registers (the subscription is
disposed on re-register). The fake editor's dispose now clears its
callback, matching real Monaco subscription semantics.

Co-authored-by: Orca <help@stably.ai>

* fix(diff): isolate navigation registration updates

* fix(diff): use arrows for change navigation

* fix(editor): tighten header action spacing

---------

Co-authored-by: Orca <help@stably.ai>
Co-authored-by: Brennan Benson <brennanbenson@Brennans-MacBook-Pro.local>
enrick-dev pushed a commit to enrick-dev/orca that referenced this pull request Oct 15, 2026
* feat(diff): add F7/Shift+F7 keyboard navigation for diff changes

Stacks on the Previous/Next change buttons (stablyai#6668) to add keyboard
navigation for single-file diffs, matching VS Code / JetBrains diff review.

- Register editor.nextChange (F7) / editor.previousChange (Shift+F7) in the
  keybinding registry (Editors group) so they show in Settings and stay
  rebindable.
- Teach the keybinding normalizer function keys (F1-F24) and make them
  first-class in the bare-key safety model (safe standalone or with Shift,
  opt-in per action) - F7 was previously unbindable.
- Install a capture-phase listener from DiffNavigationProvider so keyboard
  and the existing header buttons share one goToDiff path; works on
  read-only and editable single-file diffs.
- Translate the Previous/Next change strings for es/ja/ko/zh.

Refs stablyai#6215

* test(diff): cover change navigation shortcuts

* fix(diff): use shortcut chips in navigation tooltips

---------

Co-authored-by: Brennan Benson <brennanbenson@Brennans-MacBook-Pro.local>
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]: Add button Previous/Next Difference in Diff View

2 participants