fix(keys): match alt across terminal protocols

[benvinegar]

Summary

• make alt/option bindings match legacy Escape-prefixed Alt events and explicit ANSI/Kitty Alt events
• preserve the key protocol source when forwarding events to extensions so public matchesKey uses the same semantics
• document the unavoidable Alt/Meta overlap on legacy terminals

Testing

• bun test src/extension-api/keys.test.ts src/lib/commandKeys.test.ts src/ui/lib/extensionKeyEvent.test.ts
• bun test test/pty/key-routing.test.ts --test-name-pattern "alt binding"
• bun run typecheck
• bun run lint
• bun run format:check
• bun run deps:check
• bun run test
• bun run test:integration
• bun run build:npm
• bun run check:docs

Platforms

Tested on Linux with decoder-backed legacy, explicit ANSI, and Kitty event fixtures plus a full PTY reproduction. Not manually tested on macOS or Windows.

Known limitation

Legacy terminal input cannot distinguish an Escape-prefixed Alt key from Meta, so alt+n and meta+n may overlap there. Kitty keyboard events remain distinct.

Closes #843

[vercel]

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

Project	Deployment	Actions	Updated
hunk-web	Building	Preview	Sep 5, 2026 2:43pm UTC

[greptile-apps]

Greptile Summary

This PR makes Alt/Option bindings consistent across legacy Escape-prefixed, explicit ANSI, and Kitty keyboard events while retaining Kitty’s distinct Meta semantics.

• Adds protocol-aware modifier matching to the shared command and extension key matcher.
• Preserves terminal protocol metadata when forwarding immutable events to extensions.
• Adds unit and PTY regression coverage for legacy, ANSI, Kitty, and extension-facing paths.
• Documents the unavoidable Alt/Meta overlap in legacy terminal input.

Confidence Score: 5/5

The PR appears safe to merge, with the protocol-aware behavior covered across shared matching, extension forwarding, and PTY routing.

No actionable correctness, security, compatibility, or repository-rule violation remains; production extension event paths preserve the protocol source, and legacy Alt/Meta overlap is intentional and documented.

Important Files Changed

Filename	Overview
src/extension-api/keys.ts	Adds protocol-aware modifier matching so Alt accepts legacy encodings while Kitty Meta remains distinct.
src/extension-api/types.ts	Adds optional terminal protocol metadata to the structural public key-event type.
src/ui/lib/extensionKeyEvent.ts	Preserves the host key event’s protocol source in immutable extension-facing snapshots.
src/lib/commandKeys.test.ts	Adds decoder-backed coverage for legacy, explicit ANSI, and Kitty modifier encodings.
test/pty/key-routing.test.ts	Adds an end-to-end regression test proving a legacy Escape-prefixed Alt binding reaches command dispatch.
docs/keybindings.md	Documents cross-protocol Alt behavior and the legacy Alt/Meta ambiguity.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Terminal key sequence] --> B[OpenTUI decoder]
  B --> C{Protocol source}
  C -->|Kitty| D[Preserve distinct Alt and Meta flags]
  C -->|Raw / legacy| E[Treat Escape-prefixed Meta shape as Alt-compatible]
  D --> F[Shared matchesKeyChord matcher]
  E --> F
  F --> G[Built-in and extension command routing]
  B --> H[toExtensionKeyEvent]
  H --> I[Extension keyboard and file-view modes]
  I --> F

Loading

_{Reviews (1): Last reviewed commit: "fix(keys): match alt across terminal pro..." | Re-trigger Greptile}