authorgravatar for julius0216@outlook.comJulius Marminge <julius0216@outlook.com> 2026-02-15 14:27:37-08:00
committergravatar for jmarminge@gmail.comJulius Marminge <jmarminge@gmail.com> 2026-02-15 15:51:05-08:00
log66ebadb4483af03af479aa1b9805d7a1f45aa6cc
tree93a5ac001f65a210cddd45fb68c3c7ccd7e9d5ed
parent6667992753c3995fb591356ce8784624c6d4bd05

update doc

1 files changed, 23 insertions(+), 42 deletions(-)

KEYBINDINGS.md+23-42
...@@ -4,19 +4,6 @@ T3 Code reads keybindings from:...@@ -4,19 +4,6 @@ T3 Code reads keybindings from:
44
5- `~/.t3/keybindings.json`5- `~/.t3/keybindings.json`
66
7Schema source of truth:
8
9- [`packages/contracts/src/keybindings.ts`](packages/contracts/src/keybindings.ts)
10- [`packages/contracts/src/server.ts`](packages/contracts/src/server.ts)
11
12Server-side parsing/default resolution/merging:
13
14- [`apps/server/src/keybindings.ts`](apps/server/src/keybindings.ts)
15
16Server wiring (`server.getConfig`):
17
18- [`apps/server/src/wsServer.ts`](apps/server/src/wsServer.ts)
19
20The file must be a JSON array of rules:7The file must be a JSON array of rules:
218
22```json9```json
...@@ -26,7 +13,25 @@ The file must be a JSON array of rules:...@@ -26,7 +13,25 @@ The file must be a JSON array of rules:
26]13]
27```14```
2815
29## Rule Shape16See the full schema for more details: [`packages/contracts/src/keybindings.ts`](packages/contracts/src/keybindings.ts)
17
18## Defaults
19
20```json
21[
22 { "key": "mod+j", "command": "terminal.toggle" },
23 { "key": "mod+d", "command": "terminal.split", "when": "terminalFocus" },
24 { "key": "mod+shift+d", "command": "terminal.new", "when": "terminalFocus" },
25 { "key": "mod+shift+o", "command": "chat.new" },
26 { "key": "mod+o", "command": "editor.openFavorite" }
27]
28```
29
30For most up to date defaults, see [`DEFAULT_KEYBINDINGS` in `apps/server/src/keybindings.ts`](apps/server/src/keybindings.ts)
31
32## Configuration
33
34### Rule Shape
3035
31Each entry supports:36Each entry supports:
3237
...@@ -36,7 +41,7 @@ Each entry supports:...@@ -36,7 +41,7 @@ Each entry supports:
3641
37Invalid rules are ignored. Invalid config files are ignored. Warnings are logged by the server.42Invalid rules are ignored. Invalid config files are ignored. Warnings are logged by the server.
3843
39## Available Commands44### Available Commands
4045
41- `terminal.toggle`: open/close terminal drawer46- `terminal.toggle`: open/close terminal drawer
42- `terminal.split`: split terminal (in focused terminal context by default)47- `terminal.split`: split terminal (in focused terminal context by default)
...@@ -44,7 +49,7 @@ Invalid rules are ignored. Invalid config files are ignored. Warnings are logged...@@ -44,7 +49,7 @@ Invalid rules are ignored. Invalid config files are ignored. Warnings are logged
44- `chat.new`: create a new chat thread for the active project49- `chat.new`: create a new chat thread for the active project
45- `editor.openFavorite`: open current project/worktree in the last-used editor50- `editor.openFavorite`: open current project/worktree in the last-used editor
4651
47## Key Syntax52### Key Syntax
4853
49Supported modifiers:54Supported modifiers:
5055
...@@ -61,7 +66,7 @@ Examples:...@@ -61,7 +66,7 @@ Examples:
61- `ctrl+l`66- `ctrl+l`
62- `cmd+k`67- `cmd+k`
6368
64## `when` Conditions69### `when` Conditions
6570
66Currently available context keys:71Currently available context keys:
6772
...@@ -83,31 +88,7 @@ Examples:...@@ -83,31 +88,7 @@ Examples:
8388
84Unknown condition keys evaluate to `false`.89Unknown condition keys evaluate to `false`.
8590
86## Defaults91### Precedence
87
88Built-in defaults are resolved on the server and sent to the web client via `server.getConfig`:
89
90- Source of truth: [`DEFAULT_KEYBINDINGS` in `apps/server/src/keybindings.ts`](apps/server/src/keybindings.ts)
91
92If you define any rules for a command, the default rule for that command is removed on the server.
93
94## Server-Resolved Payload
95
96`~/.t3/keybindings.json` is parsed and compiled on the server. The web client receives resolved rules and does not parse raw keybinding strings.
97
98Resolved rule payload fields:
99
100- `command`
101- `shortcut`
102- `whenAst` (optional)
103
104See:
105
106- [`packages/contracts/src/keybindings.ts`](packages/contracts/src/keybindings.ts)
107- [`apps/server/src/keybindings.ts`](apps/server/src/keybindings.ts)
108- [`apps/server/src/wsServer.ts`](apps/server/src/wsServer.ts)
109
110## Precedence
11192
112- Rules are evaluated in array order.93- Rules are evaluated in array order.
113- For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.94- For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.