PRD: User-configurable keybindings via TOML #1

Problem Statement

Orca users cannot currently override important keyboard shortcuts. Several shortcuts are hardcoded across main-process interception, browser guest forwarding, terminal handlers, xterm bypass behavior, menus, and Settings display. This makes Orca difficult or impossible to fit into some operating system and desktop environments, especially Linux setups such as Omarchy where copy, paste, sidebar, and terminal-control chords may conflict with OS, terminal, or user muscle memory.

The problem is not limited to a single shortcut. Orca has multiple Shortcut Surfaces that see keyboard input at different layers, and prior partial approaches have missed important paths. Users need a coherent User Keybinding Config that can override audited shortcuts while preserving terminal safety, SSH behavior, and cross-platform conventions.

Solution

Add a Keybinding Catalog and per-user TOML-based User Keybinding Config. Users can edit ~/.orca/keybindings.toml on macOS/Linux or %USERPROFILE%\.orca\keybindings.toml on Windows to override or unbind keybindings.

The Keybinding Catalog becomes the source of truth for semantic Keybinding Action Ids, default Chord Sets, platform variants, Shortcut Surface metadata, display labels, Terminal Input Translation metadata, matching, and Surface-Aware Conflict validation. Main owns TOML loading, Keybinding Diagnostics, explicit Keybinding Reload, and Effective Keymap distribution. Renderer Shortcut Surfaces receive a snapshot and resolve keydown synchronously without IPC per keypress.

Settings v1 provides Read-Only Keybinding Management: effective shortcut table, default versus overridden state, config path, open/reveal actions, explicit reload, diagnostics, and starter TOML examples. An in-app keybinding editor is a follow-up after the catalog, validator, diagnostics, and reload path are proven.

User Stories

1. As a Linux user, I want to override terminal paste from Ctrl+V to Ctrl+Shift+V, so that Orca works with my desktop and terminal conventions.
2. As an Omarchy user, I want Orca shortcuts to be configurable, so that hardcoded defaults do not conflict with my OS-level keybindings.
3. As a macOS user, I want Orca to preserve Command-key conventions by default, so that the app still feels native after keybinding customization lands.
4. As a Windows user, I want user keybindings to work from my Windows home directory, so that configuration is not Linux/macOS-only.
5. As a user who works across platforms, I want platform-specific keybinding tables, so that my macOS, Linux, and Windows shortcuts can differ intentionally.
6. As a user who only cares about one OS, I want concrete key names like cmd, option, ctrl, alt, and shift, so that the config matches keys I can see on my keyboard.
7. As a terminal user, I want to override terminal copy and paste without breaking Ctrl+C as SIGINT, so that shell workflows stay intact.
8. As a terminal user, I want bare Ctrl+C to continue reaching the shell when no text is selected, so that interrupt behavior remains reliable.
9. As a terminal user, I want Ctrl+D to continue working as EOF on Linux and Windows, so that closing shells and REPLs is not broken by app shortcuts.
10. As a user, I want to explicitly unbind a default shortcut, so that I can remove conflicts instead of moving them to another chord.
11. As a user, I want one action to support multiple chords, so that compatibility aliases such as terminal paste alternatives can coexist.
12. As a user, I want a single chord string for the common case, so that basic customization stays simple.
13. As a user, I want an array of chords for advanced cases, so that I can preserve or define multiple useful aliases.
14. As a user, I want none to mean unbound, so that disabling a shortcut is clear and easy to audit.
15. As a user, I want invalid entries to be ignored rather than crashing Orca, so that a typo in the config file does not block app startup.
16. As a user, I want diagnostics for invalid entries, so that I can fix typos, unknown action ids, invalid chord syntax, and conflicts.
17. As a user, I want to see which shortcuts are defaults and which are overridden, so that I can understand my Effective Keymap.
18. As a user, I want Settings to show the keybindings config path, so that I can find and edit the right file.
19. As a user, I want Settings to open the keybindings file, so that I do not need to remember the path.
20. As a user, I want Settings to reveal the keybindings file location, so that I can manage it with my editor or file manager.
21. As a user, I want to reload keybindings explicitly after editing the TOML file, so that changes take effect without restarting Orca.
22. As a user, I want Orca to avoid automatic file watching in v1, so that partial writes from my editor do not create confusing transient diagnostics.
23. As a user, I want starter TOML examples in Settings, so that I can copy a known-good configuration shape.
24. As a Linux user, I want Omarchy-friendly examples, so that I can quickly restore terminal-native copy and paste behavior.
25. As a user, I want Orca to preserve existing defaults unless I override them, so that upgrading does not unexpectedly change my workflow.
26. As a maintainer, I want the Keybinding Catalog to be the single source of truth, so that Settings labels, menu hints, and runtime behavior do not drift.
27. As a maintainer, I want shortcut resolution to stay synchronous during keydown, so that terminal, browser, and main-process shortcut handling remains responsive and deterministic.
28. As a maintainer, I want main-owned TOML loading and renderer snapshots, so that privileged file I/O stays out of renderer shortcut handling.
29. As a maintainer, I want pure shared modules for parsing, matching, labels, and conflict validation, so that the hard logic can be tested without Electron.
30. As a maintainer, I want Surface-Aware Conflict validation, so that the same chord can be allowed in mutually exclusive surfaces but rejected when surfaces overlap.
31. As a maintainer, I want global/main-process shortcuts to be treated as overlapping most surfaces, so that they do not silently steal terminal or browser chords.
32. As a maintainer, I want real Electron menu accelerators to participate in conflict validation, so that menu shortcuts do not bypass the catalog.
33. As a maintainer, I want display-only menu labels to come from the Effective Keymap, so that UI hints stay accurate without intercepting input incorrectly.
34. As a terminal user over SSH, I want terminal input translations to remain named and reviewed, so that Orca does not introduce arbitrary PTY byte injection through config.
35. As an SSH user, I want remote shells, tmux, editors, and TUIs to receive expected terminal bytes, so that local customization does not break remote workflows.
36. As a terminal power user, I want named terminal input translations such as word-left, word-right, line-start, and line-end to be rebindable, so that terminal navigation can match my environment.
37. As a terminal power user, I do not want arbitrary byte sequences in v1, so that keybinding customization remains safe and understandable.
38. As a macOS user with a non-US keyboard layout, I want Option-as-Alt behavior to remain governed by the existing terminal setting, so that keybinding TOML does not break special character composition.
39. As a macOS user, I want named Option-based terminal input actions to be cataloged where appropriate, so that common readline shortcuts remain configurable.
40. As a user, I want unknown action ids to be reported clearly, so that stale or misspelled config entries are easy to remove.
41. As a user, I want invalid chord strings to be reported clearly, so that I can correct the value without guessing what failed.
42. As a user, I want conflicting overrides to be reported clearly, so that I understand why a shortcut did not apply.
43. As a user, I want valid entries to keep applying even when other entries are invalid, so that one mistake does not discard my whole config.
44. As a user, I want the config file to preserve comments and ordering, so that my hand-edited TOML remains readable.
45. As a maintainer, I want reload to read TOML without rewriting it, so that Orca avoids comment-destroying config churn.
46. As a maintainer, I want smol-toml as a direct dependency, so that the parser dependency is explicit and reliable.
47. As a Settings user, I want the Shortcuts pane to be useful before an in-app editor exists, so that I can discover and debug customization in v1.
48. As a future contributor, I want an accepted design captured in ADR 0001, so that implementation does not reopen settled product and architecture decisions.
49. As a future contributor, I want the in-app keybinding editor to build on the v1 catalog and diagnostics, so that it does not create a second persistence model.
50. As a reviewer, I want tests around behavior rather than implementation details, so that refactoring internal tables does not break tests unnecessarily.

Implementation Decisions

• Build a deep Keybinding Catalog module that owns semantic Keybinding Action Ids, default Chord Sets, platform variants, display metadata, Shortcut Surface metadata, Terminal Input Translation metadata, and conflict metadata.
• Build a pure chord parser and Canonical Chord normalizer that accepts user-facing concrete modifier names, normalizes spelling/case/order, and supports platform-aware display labels.
• Do not document mod as a public v1 token. Cross-platform modifier aliases may exist internally for catalog defaults and implementation convenience.
• Build a Surface-Aware Conflict validator that checks platform plus overlapping Shortcut Surfaces rather than rejecting every duplicate chord globally.
• Build a main-owned User Keybinding Config loader for the user home .orca directory.
• Add smol-toml as a direct dependency for main-process parsing.
• The TOML schema is action-id based, with optional platform-specific tables for macOS, Linux, and Windows.
• A top-level shared keybinding table is allowed, but Settings examples should prefer platform-specific tables with concrete OS key names.
• Override values can be a single chord string, an array of chord strings, or none.
• An override replaces the full Chord Set for that action on that platform.
• none explicitly unbinds an action on that platform and prevents fallback to defaults.
• Empty strings are invalid and should produce Keybinding Diagnostics rather than unbinding.
• Unknown action ids, invalid chord syntax, invalid table shape, and Surface-Aware Conflicts are reported as diagnostics.
• Invalid entries are ignored while valid entries continue applying.
• Orca must remain usable with catalog defaults if the config file is missing, unreadable, malformed, or partially invalid.
• The main process owns Effective Keymap creation, diagnostics, explicit reload, menu refresh, and renderer snapshot distribution.
• Renderer Shortcut Surfaces receive an Effective Keymap snapshot and resolve keydown synchronously.
• Keydown handling must never call IPC to resolve a shortcut.
• Main-process window interception must be migrated from hardcoded policy to the Effective Keymap.
• Browser guest forwarding must be migrated from hardcoded policy to the Effective Keymap where it handles audited shortcuts.
• Terminal command shortcuts must be migrated to the Effective Keymap while preserving terminal-control carve-outs.
• Terminal paste must become a cataloged action so users can rebind it and remove problematic defaults.
• Xterm bypass behavior must consult the Effective Keymap or derived clipboard bypass metadata so copy and paste behavior remains aligned.
• Menu labels and accelerators must derive from the catalog or Effective Keymap where possible.
• Display-only menu labels must stay display-only when real accelerators would bypass renderer or main-process carve-outs.
• Settings > Shortcuts becomes Read-Only Keybinding Management in v1.
• Settings v1 shows effective shortcuts, default versus overridden state, unbound state, config path, open/reveal controls, explicit reload, diagnostics, and starter TOML examples.
• In-app keybinding recording/editing is intentionally deferred to a follow-up.
• Do not write TOML during normal reload. Preserve user comments and ordering by reading only.
• If Orca creates a missing keybindings file, it may write a starter template once.
• Preserve existing platform defaults in v1. Do not silently change Linux/Windows copy-paste defaults as part of this refactor.
• Provide Omarchy-friendly examples rather than changing defaults for every Linux user.
• Terminal Input Translation overrides are limited to named catalog actions.
• Do not support arbitrary user-defined PTY byte sequences in v1.
• Keep macOS Option-as-Alt mode under the existing terminal setting, not general TOML keybindings.
• Catalog only named semantic terminal input actions for Option-related behavior.
• Local widget-specific keydown semantics remain out of scope for v1 unless they are part of an audited Shortcut Surface.
• The accepted architecture decisions are documented in ADR 0001.

Testing Decisions

• Tests should focus on external behavior: given catalog defaults, platform, config input, and key events, assert the resulting Effective Keymap, diagnostics, and resolved actions.
• Avoid tests that lock down incidental table ordering or private implementation details except where ordering is itself a user-visible conflict rule.
• Unit test the chord parser and Canonical Chord normalizer across case, spacing, modifier ordering, punctuation, arrows, and invalid inputs.
• Unit test platform-specific modifier handling for macOS, Linux, and Windows.
• Unit test User Keybinding Config parsing for missing file, malformed TOML, unknown ids, invalid platform tables, string values, array values, and none values.
• Unit test that invalid entries are ignored while valid entries still apply.
• Unit test Chord Set replacement semantics, including single string, array, and explicit unbinding.
• Unit test Surface-Aware Conflict validation for overlapping and mutually exclusive Shortcut Surfaces.
• Unit test global/main-process shortcut conflicts against terminal and browser surfaces.
• Unit test menu accelerator conflicts separately from display-only menu labels.
• Unit test Terminal Input Translation actions by asserting named actions map to expected terminal behavior, not by allowing arbitrary bytes from config.
• Add parity tests ensuring Settings display labels come from the same catalog/Effective Keymap used by runtime resolution.
• Add tests that existing default copy/paste behavior is preserved when no config file exists.
• Add tests for Omarchy-style Linux overrides, including terminal paste moved to Ctrl+Shift+V and problematic defaults unbound.
• Add tests that macOS Option-as-Alt setting behavior remains separate from keybinding TOML.
• Add main-process reload tests verifying reload updates diagnostics, refreshes the Effective Keymap, and triggers menu/snapshot updates.
• Add renderer snapshot tests verifying keydown resolution remains synchronous and uses the latest delivered Effective Keymap.
• Add tests for xterm bypass behavior so copy and paste bypass metadata stays aligned with configured clipboard actions.
• Add Settings tests for read-only management UI states: default, overridden, unbound, diagnostics present, and config missing.
• Reuse the existing style of shortcut policy tests, terminal shortcut tests, xterm bypass tests, menu tests, settings tests, and terminal shortcut E2E tests as prior art.
• Include at least one E2E or integration-level terminal clipboard flow for the most important configured copy/paste path if reliable in CI.
• Include cross-platform review notes in the PR because shortcuts, labels, paths, shell behavior, and Electron accelerator behavior are touched.

Out of Scope

• In-app keybinding editor or key recorder.
• Automatic file watching for keybindings.toml.
• Arbitrary user-defined PTY byte sequences.
• Repo-level keybinding overrides.
• Persisting keybindings in app-owned JSON state.
• Rewriting user TOML on normal reload.
• Changing Linux, Windows, or macOS default shortcuts as part of v1.
• Migrating every local widget keydown into the catalog.
• Replacing the macOS Option-as-Alt terminal setting with keybinding TOML.
• Multi-step key sequences or chord chains.
• Per-worktree or per-repository shortcut profiles.
• Cloud sync of keybinding configuration.

Further Notes

This PRD follows the accepted keybinding customization design in ADR 0001. The implementation should use the project vocabulary from the Orca Keyboard Customization context: Keybinding Catalog, User Keybinding Config, Shortcut Surface, Audited Shortcut Surface, Terminal Input Translation, Keybinding Action Id, Surface-Aware Conflict, Effective Keymap, Keybinding Reload, Canonical Chord, Keybinding Diagnostics, Read-Only Keybinding Management, Explicit Unbinding, and Chord Set.

Prior PRs are important context. PR stablyai#499 is useful as a UI sketch but is not sufficient because it stored overrides in app state and missed important audited surfaces. PR stablyai#519 demonstrates why shortcut interception needs centralized policy and regression tests. PR stablyai#859 supports the direction of declarative terminal shortcut data and docs/test parity.

The implementation should be decomposed into deep, testable modules so that the catalog, parser, config loader, validator, and diagnostics can be tested without Electron before they are wired into main and renderer Shortcut Surfaces.