feat: configurable keyboard bindings

[jesse23]

Summary

• Adds keyboardBindings config array to ~/.config/webtty/config.json — each entry maps a key+mods combo to a raw PTY byte sequence (chars)
• Implements a capture-phase keydown handler in the browser client that intercepts matching key combos before ghostty-web sees them and sends chars directly to the PTY over WebSocket
• Recommends the kitty keyboard protocol format for chars values (e.g. "\u001b[13;2u" for Shift+Enter) — verified working with opencode and Helix

Changes

Docs

• docs/adrs/018.client.keyboard-bindings.md — new ADR covering design rationale, schema decisions, and considered options
• docs/specs/config.md — keyboardBindings schema, how-to guide with kitty protocol formula, binding examples, and conversion table from other terminals
• docs/specs/client.md — keyboard bindings section describing the capture-phase interception approach

Implementation

• src/config.ts — KeyboardBinding interface, keyboardBindings field on Config, mergeKeyboardBindings helper, DEFAULT_KEYBOARD_BINDINGS = []
• src/server/routes.ts — keyboardBindings added to /api/config whitelist
• src/client/index.ts — capture-phase keydown listener with set-based mod matching
• src/config.test.ts — 100% function + line coverage including direct mergeKeyboardBindings unit tests

[Copilot]

Pull request overview

Adds a new keyboardBindings configuration surface so the browser client can intercept specific keydown combos (key + modifiers) and send configured byte sequences directly to the PTY, improving compatibility with TUIs expecting kitty-keyboard-protocol (or other) sequences.

Changes:

• Adds keyboardBindings to the config model, default config, config merging, and /api/config whitelist.
• Implements a capture-phase keydown interceptor in the browser client to match bindings and send chars over WebSocket.
• Documents the schema/usage via a new ADR and updates to the config/client specs, plus adds unit tests around merging/loading.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/server/routes.ts	Exposes keyboardBindings via GET /api/config.
src/config.ts	Introduces KeyboardBinding, defaults, and merge logic; wires into loadConfig().
src/client/index.ts	Adds capture-phase keydown handler to intercept bindings and send chars to PTY.
src/config.test.ts	Adds tests for keyboardBindings load/merge behavior.
docs/specs/config.md	Documents keyboardBindings schema and examples.
docs/specs/client.md	Documents the client interception approach and config payload shape.
docs/adrs/018.client.keyboard-bindings.md	New ADR describing rationale, schema, and approach.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.