feat(desktop): shortcut through terminal panes

[AviPeltz]

Description

Related Issues

Type of Change

• Bug fix
• New feature
• Documentation
• Refactor
• Other (please describe):

Testing

Screenshots (if applicable)

Additional Notes

Summary by CodeRabbit

• New Features
  • Added keyboard shortcuts to move focus between panes in the active tab: Cmd+Alt+Left (previous) and Cmd+Alt+Right (next).
  • Pane switching follows the visual layout order, wraps at ends, and safely handles single-pane tabs.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds keyboard pane navigation: two hotkeys (meta+alt+left/right), utilities to compute next/previous pane IDs in mosaic layouts (visual order, circular), and handlers in WorkspaceView that use those utils and the tabs store to move focused pane.

Changes

Cohort / File(s)	Summary
Hotkey definitions apps/desktop/src/shared/hotkeys.ts	Added PREV_PANE (meta+alt+left) and NEXT_PANE (meta+alt+right) hotkey entries with labels, descriptions, and category "Terminal".
Pane navigation utilities apps/desktop/src/renderer/stores/tabs/utils.ts	Added getPaneIdsInVisualOrder(layout), getNextPaneId(layout, currentPaneId), and getPreviousPaneId(layout, currentPaneId) to list pane IDs in visual (L→R, T→B) order and compute next/previous IDs with circular wrap and edge-case handling.
Workspace integration apps/desktop/src/renderer/screens/main/components/WorkspaceView/index.tsx	Imported new utils and setFocusedPane selector; introduced memoized activeTab and hotkey handlers for PREV_PANE and NEXT_PANE that validate activeTabId, activeTab.layout, and focusedPaneId, compute target pane via utils, and call setFocusedPane.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant User as User (keyboard)
participant Workspace as WorkspaceView
participant Utils as Pane Utils
participant Store as Tabs Store

Note over User,Workspace: user presses meta+alt+left/right
User->>Workspace: emit hotkey event (PREV_PANE / NEXT_PANE)
Workspace->>Workspace: validate activeTabId, activeTab.layout, focusedPaneId
Workspace->>Utils: getPreviousPaneId(layout, focusedPaneId) / getNextPaneId(layout, focusedPaneId)
Utils-->>Workspace: return targetPaneId (or null)
Workspace->>Store: call setFocusedPane(targetPaneId)
Store-->>Workspace: update focused pane state
Workspace-->>User: UI reflects new focused pane

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review traversal logic and wrap behavior in utils.
• Verify hotkey registration, key choices, and integration with WorkspaceView handlers.
• Confirm store selector invocation shape and state validation guards.

Possibly related PRs

• refactor window to tabs lmao  #284 — Directly related: builds on tabs refactor and adds similar visual-order pane navigation helpers and hotkey wiring.
• hotkey pane #108 — Adds keyboard-driven pane navigation and focus handlers; overlaps with this PR's feature area.
• Remove custom hotkeys handler in favor of react-hotkeys-hook #114 — Modifies WorkspaceView hotkey handling; relevant to integration and keybinding choices.

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The PR description follows the template structure but lacks substantive content; all sections are either empty or only contain template comments without actual information.	Fill in the Description section with details about the shortcut implementation, add Related Issues if applicable, clarify the Type of Change (appears to be a new feature, not a bug fix), include testing steps, and provide any relevant additional context.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(desktop): shortcut through terminal panes' clearly and concisely summarizes the main change—adding keyboard shortcuts to navigate between terminal panes.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch shortcut-tab-between-panes

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 885e7bd and a9b5fd5.

📒 Files selected for processing (1)

• apps/desktop/src/renderer/stores/tabs/utils.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• apps/desktop/src/renderer/stores/tabs/utils.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[charliecreates]

Pane navigation is implemented cleanly, but there’s a suboptimal lookup for activeTab (searching allTabs instead of workspace-filtered tabs) and a potential avoidable traversal cost in getNextPaneId/getPreviousPaneId if extractPaneIdsFromLayout is non-trivial. Neither is likely to break functionality, but the first is worth fixing for correctness/robustness and performance.

Additional notes (1)

• Performance | apps/desktop/src/renderer/stores/tabs/utils.ts:214-243
getNextPaneId / getPreviousPaneId call extractPaneIdsFromLayout(layout) on every hotkey press. If extractPaneIdsFromLayout walks the full mosaic tree, this is O(n) traversal per keypress. That’s likely fine for small layouts, but it can become noticeable with larger/complex layouts.

Since layout only changes when the tab layout changes, consider memoizing the extracted pane ID list (in the caller) or providing a utility that can compute the “next” pane without flattening the entire tree each time.

Summary of changes

What changed

• Added pane focus hotkeys in WorkspaceView:

  • New handlers for HOTKEYS.PREV_PANE / HOTKEYS.NEXT_PANE that call setFocusedPane(activeTabId, paneId).
  • Introduced activeTab memoization to access activeTab.layout.
  • Imported new helpers getNextPaneId / getPreviousPaneId from renderer/stores/tabs/utils.

• Extended tab layout utilities (apps/desktop/src/renderer/stores/tabs/utils.ts):

  • Added getNextPaneId(layout, currentPaneId) and getPreviousPaneId(layout, currentPaneId) which traverse pane IDs (via extractPaneIdsFromLayout) and wrap around.

• Registered new hotkey definitions (apps/desktop/src/shared/hotkeys.ts):

  • meta+alt+left → Previous Pane
  • meta+alt+right → Next Pane

Links: WorkspaceView → apps/desktop/src/renderer/screens/main/components/WorkspaceView/index.tsx, utilities → apps/desktop/src/renderer/stores/tabs/utils.ts, hotkeys → apps/desktop/src/shared/hotkeys.ts.

[charliecreates]

Pane navigation is implemented cleanly, but activeTab is looked up via allTabs.find(...) instead of the already workspace-filtered tabs, which is both extra work and less robust. Additionally, getNextPaneId/getPreviousPaneId implicitly depend on the traversal order of extractPaneIdsFromLayout(layout); for a user-facing hotkey, the navigation order should be explicit and aligned with the UI’s visual ordering. Addressing these will improve correctness and predictability without changing the feature’s intent.

Summary of changes

Summary of changes

• Added pane-navigation hotkeys to WorkspaceView:

  • Registers HOTKEYS.PREV_PANE / HOTKEYS.NEXT_PANE and calls setFocusedPane(activeTabId, paneId).
  • Introduces activeTab memoization to access activeTab.layout.
  • Uses new helpers getNextPaneId / getPreviousPaneId from renderer/stores/tabs/utils.

• Extended tab layout utilities in apps/desktop/src/renderer/stores/tabs/utils.ts:

  • Adds getNextPaneId(layout, currentPaneId) and getPreviousPaneId(layout, currentPaneId).
  • Both functions flatten pane IDs via extractPaneIdsFromLayout(layout) and wrap at ends.

• Registered new hotkey definitions in apps/desktop/src/shared/hotkeys.ts:

  • meta+alt+left → “Previous Pane”
  • meta+alt+right → “Next Pane”

Files touched:

• apps/desktop/src/renderer/screens/main/components/WorkspaceView/index.tsx
• apps/desktop/src/renderer/stores/tabs/utils.ts
• apps/desktop/src/shared/hotkeys.ts

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ff4a3f8 and 885e7bd.

📒 Files selected for processing (2)

• apps/desktop/src/renderer/screens/main/components/WorkspaceView/index.tsx
• apps/desktop/src/renderer/stores/tabs/utils.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• apps/desktop/src/renderer/screens/main/components/WorkspaceView/index.tsx

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Avoid using any type in TypeScript - maintain type safety unless absolutely necessary

Files:

• apps/desktop/src/renderer/stores/tabs/utils.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (AGENTS.md)

Run Biome for formatting, linting, import organization, and safe fixes at the root level using bun run lint:fix

Files:

• apps/desktop/src/renderer/stores/tabs/utils.ts

apps/desktop/src/renderer/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Never import Node.js modules in renderer process or shared code - use only in main process (src/main/)

Files:

• apps/desktop/src/renderer/stores/tabs/utils.ts

apps/desktop/src/{main,renderer,preload}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use type-safe IPC communication - define channel types in apps/desktop/src/shared/ipc-channels.ts before implementing handlers

Files:

• apps/desktop/src/renderer/stores/tabs/utils.ts

apps/desktop/**/*.{ts,tsx}

📄 CodeRabbit inference engine (apps/desktop/AGENTS.md)

apps/desktop/**/*.{ts,tsx}: For Electron interprocess communication, ALWAYS use tRPC as defined in src/lib/trpc
Use alias as defined in tsconfig.json when possible
Prefer zustand for state management if it makes sense. Do not use effect unless absolutely necessary.
For tRPC subscriptions with trpc-electron, ALWAYS use the observable pattern from @trpc/server/observable instead of async generators, as the library explicitly checks isObservable(result) and throws an error otherwise

Files:

• apps/desktop/src/renderer/stores/tabs/utils.ts

🧬 Code graph analysis (1)

apps/desktop/src/renderer/stores/tabs/utils.ts (1)

apps/desktop/src/shared/types/mosaic.ts (1)

• MosaicNode (1-8)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build

🔇 Additional comments (2)

apps/desktop/src/renderer/stores/tabs/utils.ts (2)

244-260: LGTM! Clean implementation of circular next-pane navigation.

The logic correctly handles:

• Single-pane layouts (returns null)
• Unknown current pane (fallback to first)
• Wraparound from last to first

The comprehensive documentation in getPaneIdsInVisualOrder addresses the previous review concern about visual order semantics.

---

262-278: LGTM! Correct implementation of circular previous-pane navigation.

The logic correctly handles:

• Single-pane layouts (returns null)
• Unknown current pane (fallback to last)
• Wraparound from first to last with proper modulo arithmetic (+ paneIds.length prevents negatives)

The implementation appropriately mirrors getNextPaneId in reverse.

[github-actions]

🧹 Preview Cleanup Complete

The following preview resources have been cleaned up:

Service	Status
Database (Neon)	⚠️

Thank you for your contribution! 🎉

---

Preview resources have been processed for cleanup