refactor: rework the keybinding system for TUI

[kxxt]

Separate concrete actions from keyboard keys.

Summary by CodeRabbit

• Usability

  • Keyboard shortcuts now follow configured bindings consistently throughout panes, popups, query tools, terminals, event lists, and editors.
  • When multiple actions share a key, the intended priority order is respected.

• Bug Fixes

  • Customized key bindings are now recognized consistently across the interface.
  • Keyboard actions continue to work reliably for navigation, scrolling, searching, copying, pane switching, and closing dialogs.

• Refactor

  • Centralized keyboard handling improves consistency without changing existing shortcut actions.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
tracexec	Ready	Preview	Sep 18, 2026 3:47pm UTC

[coderabbitai]

Warning

Review limit reached

Next included review available in 26 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 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: Path: .coderabbit.yml

Review profile: CHILL

Plan: Advanced

Run ID: 2a03d899-4f45-42e3-9a26-517125040dee

📥 Commits

Reviewing files that changed from the base of the PR and between a4d9217 and a7db981.

📒 Files selected for processing (1)

• crates/tracexec-core/src/cli/keys.rs

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Advanced

Run ID: c1678900-7a71-49fa-aa95-b4024b8b4aee

📥 Commits

Reviewing files that changed from the base of the PR and between 840fd18 and a4d9217.

📒 Files selected for processing (1)

• crates/tracexec-tui/src/copy_popup.rs

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

---

Walkthrough

The change adds centralized key-action definitions and routing. The TUI delegates application key events to a keyboard module. Popup, event-list, breakpoint, hit-manager, terminal, and query handlers use the shared router.

Changes

Centralized TUI key routing

Layer / File(s)	Summary
Key router contract crates/tracexec-core/src/cli/keys.rs	The key_actions! macro generates KeyAction and binding lookup. KeyRouter matches events and resolves the first matching action. Tests cover priority ordering and customized bindings.
Application key dispatch crates/tracexec-tui/src/app.rs, crates/tracexec-tui/src/app/keyboard.rs	App::run delegates key events to route_key_event. The new routing method handles pane, popup, manager, query, layout, terminal, and event-list paths. Pane switching resets related state.
Popup and event-list routing crates/tracexec-tui/src/backtrace_popup.rs, crates/tracexec-tui/src/copy_popup.rs, crates/tracexec-tui/src/details_popup.rs, crates/tracexec-tui/src/event_list/react.rs	Popup and event-list handlers replace direct binding-field checks with KeyRouter and KeyAction matches. Copy-popup tests cover shortcut selection, remapping, availability, and control priority.
State and terminal routing crates/tracexec-tui/src/breakpoint_manager.rs, crates/tracexec-tui/src/hit_manager.rs, crates/tracexec-tui/src/pseudo_term.rs, crates/tracexec-tui/src/query.rs	Breakpoint, hit-manager, terminal, and query handlers use centralized action matching. Query text handling receives the routed event through KeyRouter::event().

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Refactor

Sequence Diagram(s)

sequenceDiagram
  participant App
  participant KeyRouter
  participant QueryBuilder
  participant EventList
  participant ActionChannel
  App->>KeyRouter: match key actions by priority
  KeyRouter->>QueryBuilder: route query actions
  KeyRouter->>EventList: route event-list actions
  QueryBuilder->>ActionChannel: send query action
  EventList->>ActionChannel: send event action

Loading

Merge Risk: ⚪ Minimal · up to a4d92

The refactor preserves existing key handling behavior and is ready to merge after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.59% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 34 functions across 11 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and clearly summarizes the main change: refactoring the TUI keybinding system.
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 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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.}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no actionable new issue or outstanding previous finding remains.

Findings

1.  Copy Actions Bypass Router ▶

Fix with agent prompt

### Issue 1
crates/tracexec-core/src/cli/keys.rs:420-430
The new `KeyAction` API exposes eleven `CopyTarget*` variants, but the copy popup still matches these shortcuts through `copy_target_binding()` instead of `KeyRouter`. This leaves part of the action-routing API unused and creates two dispatch mechanisms that future keybinding changes must keep synchronized. Route copy-target selection through these actions, or remove the unused variants.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

This PR separates TUI actions from their physical key bindings and centralizes configurable key dispatch through KeyAction and KeyRouter.

• Adds action-based binding lookup and deterministic component-level priority resolution.
• Migrates panes, popups, query editing, event navigation, breakpoint handling, hit handling, and terminal scrollback to routed actions.
• Routes copy-target shortcuts through the centralized action API, fully addressing the previous review finding.
• Adds tests for customized bindings, action priority, copy-target availability, and remapping behavior.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    E[KeyEvent] --> R[KeyRouter]
    R --> B[TuiKeyBindings]
    B --> A[Resolve KeyAction]
    A --> P{Active UI context}
    P -->|Popup| PO[Popup handler]
    P -->|Manager or editor| M[Manager/editor handler]
    P -->|Events pane| EL[Event-list handler]
    P -->|Terminal pane| T[Terminal handler]
    PO --> O[Action]
    M --> O
    EL --> O
    T --> O

Loading

_{Reviews (3) · Last reviewed commit: "refactor: rework the keybinding system f..."}

[codecov]

Codecov Report

❌ Patch coverage is 81.61290% with 57 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.93%. Comparing base (c3f95dc) to head (a7db981).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/tracexec-tui/src/app/keyboard.rs	53.27%	50 Missing ⚠️
crates/tracexec-core/src/cli/keys.rs	91.17%	3 Missing ⚠️
crates/tracexec-tui/src/query.rs	71.42%	2 Missing ⚠️
crates/tracexec-tui/src/backtrace_popup.rs	0.00%	1 Missing ⚠️
crates/tracexec-tui/src/copy_popup.rs	98.80%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #325      +/-   ##
==========================================
+ Coverage   82.62%   82.93%   +0.30%     
==========================================
  Files          84       85       +1     
  Lines       21577    21676      +99     
==========================================
+ Hits        17829    17976     +147     
+ Misses       3748     3700      -48     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.