feat: add custom key mapping system

[ryanbbrown]

Summary

• Adds custom key mappings: users define key combos and what the terminal sends (ignore, escape sequence, hex code, or text)
• Includes a "Natural Text Editing (iTerm2)" preset that maps common macOS text navigation shortcuts (⌥/⌘ + arrows, backspace, delete) with one click
• Fixes bug where two attachCustomKeyEventHandler calls silently overwrote each other (Shift+Enter handler was lost by the macOS Option key handler). All key interception is now consolidated into a single KeyMappingAddon.

Key mapping preset: Natural Text Editing

Shortcut	Action
⌥←	Word backward
⌥→	Word forward
⌘←	Beginning of line
⌘→	End of line
⌥⌫	Delete word backward
⌘⌫	Delete to beginning of line
⌥Delete	Delete word forward

🤖 Generated with Claude Code

[ryanbbrown]

Hey! Just bumping this, wondering if it might get a review at some point? Happy to make any revisions needed. I've been using this feature daily in my own setup and it's been working well, I think custom key mappings would be a nice addition to the plugin.

[janah01]

Hey @ryanbbrown, thanks for taking the time to contribute this PR. Let me go through each point:

1. attachCustomKeyEventHandler overwrite bug

This was already fixed on main in commit e023673, which consolidated Shift+Enter and macOS Option-key handling into a single CustomKeyEventHandlerAddon. There is now only one attachCustomKeyEventHandler call in the codebase, so I think this part of the PR is no longer needed.

2. Natural Text Editing preset

Four of the seven bindings in the preset are already shipped on main from the same commit: ⌥← / ⌥→ for word navigation, and ⌥⌫ / ⌥Delete for word deletion. What was overlooked were the ⌘ combos: ⌘← / ⌘→ for beginning/end of line, and ⌘⌫ for delete to beginning of line. Those are really needed.

That said, I don't think these seven key mappings should be a loadable preset. Every macOS terminal user expects ⌥ / ⌘ + Arrow / Backspace etc .. to just work. They are really baseline terminal UX on macOS. The plugin already treats macOS key handling as its responsibility (macOptionIsMeta forced off, platform-gated addon, hardcoded macOS Option-key handling), so these belong in the same category.

3. Configurable key mapping system

The concept is genuinely useful for user-defined bindings beyond the standard set, but I think it needs its own follow-up issue/PR. A few things need to be considered first:

• In its current form, user mappings run before the existing guard, which means the duplicated ⌥ bindings in the preset would bypass the macOSOptionKeyPassthrough toggle.
• keyMappings needs runtime platform gating. The plugin syncs settings globally and gates at runtime, same as macOSOptionKeyPassthrough, so e.g. ⌘ mappings should not activate on Linux or Windows, where Meta+Arrow has OS-level meaning.
• The ⌘ bindings should also be independent of the macOSOptionKeyPassthrough toggle. That setting gates Option-key passthrough, not Command-key shortcuts.

This would also require an architectural decision: one suggestions could be one key-event router with a priority pipeline (invariant rules -> input compatibility -> user custom bindings -> platform defaults -> xterm fallthrough), persisting only deltas instead of full binding sets.

What I’d suggest for this PR is rebasing onto current main and slimming it down to just the three ⌘ bindings inside the existing CustomKeyEventHandlerAddon, with the same macOS platform gate but independent of the Option passthrough toggle. Since this particular fix is really needed, I can help push the changes directly and merge your PR.

For the user-configurable mapping system, I suggest you open an issue or a follow up PR.

Let me know if you have questions, we can discuss further.