stablyai--orca/docs/reference/keyboard-layout-shortcut-dispatch.md

Keyboard Layout Shortcut Dispatch

Problem

Keyboard shortcuts must follow the user's active keyboard layout. A shortcut like Cmd+W means "Command plus the key that produces w", not "Command plus the physical key labeled W on a US keyboard." Physical-position matching breaks Dvorak, Colemak, AZERTY, JIS, and other non-US layouts, and it also makes user keybinding overrides impossible to reason about.

Decision

Orca app shortcuts dispatch by logical key by default.

The shared keybinding registry in src/shared/keybindings.ts is the source of truth for app commands, configurable commands, shortcut recording, labels, conflict detection, browser guest forwarding, and terminal pane commands. Code handling a user-facing app command must call keybindingMatchesAction, keybindingMatchesInput, or a policy function built on those helpers.

Physical KeyboardEvent.code may only decide a shortcut when the key is layout-invariant or the platform cannot provide a real logical key.

Allowed physical-code uses:

• Modifier key release tracking, such as left/right Control release for held Ctrl+Tab.
• Layout-invariant keys, such as arrows, Tab, Enter, Escape, Backspace, Delete, Insert, PageUp, PageDown, and explicit numpad bindings.
• Dead, unidentified, or missing logical keys where KeyboardEvent.key cannot describe the produced key.
• Terminal byte encoding where the intent is a physical terminal escape sequence rather than an Orca command.

Disallowed physical-code uses:

• Letter shortcuts for app actions.
• Punctuation shortcuts for app actions when KeyboardEvent.key reports the produced punctuation.
• Clipboard shortcuts that are exposed as app or terminal UI commands.
• Hardcoded undo/redo/new/close/copy/paste handling outside the shared registry.

Terminal Boundary

Terminal handling has two different jobs:

1. Orca commands that act on terminal UI, such as copy selection, paste, search, clear, pane focus, split, and close. These are app shortcuts and must be layout-aware.
2. Bytes sent to the shell, such as readline escapes and Option-as-Alt sequences. These may use physical key positions when terminal compatibility requires it.

This boundary is intentional. It lets non-US layouts use Orca commands naturally while preserving shell behavior where users expect physical terminal-control sequences.

Regression Requirements

Shortcut tests must cover both directions of a non-QWERTY swap:

• The key that produces the configured logical character must match, even if its physical code differs.
• The physical US key must not match when it produces a different logical character.

Tests must also cover intentional exceptions:

• Dead or missing key fallback.
• Shifted punctuation aliases.
• Numpad-specific bindings.
• Terminal byte-encoding paths that intentionally use physical codes.