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:
44
55- `~/.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
207The file must be a JSON array of rules:
218
229```json
......@@ -26,7 +13,25 @@ The file must be a JSON array of rules:
2613]
2714```
2815
29## Rule Shape
16See 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
3136Each entry supports:
3237
......@@ -36,7 +41,7 @@ Each entry supports:
3641
3742Invalid rules are ignored. Invalid config files are ignored. Warnings are logged by the server.
3843
39## Available Commands
44### Available Commands
4045
4146- `terminal.toggle`: open/close terminal drawer
4247- `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
4449- `chat.new`: create a new chat thread for the active project
4550- `editor.openFavorite`: open current project/worktree in the last-used editor
4651
47## Key Syntax
52### Key Syntax
4853
4954Supported modifiers:
5055
......@@ -61,7 +66,7 @@ Examples:
6166- `ctrl+l`
6267- `cmd+k`
6368
64## `when` Conditions
69### `when` Conditions
6570
6671Currently available context keys:
6772
......@@ -83,31 +88,7 @@ Examples:
8388
8489Unknown condition keys evaluate to `false`.
8590
86## Defaults
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
91### Precedence
11192
11293- Rules are evaluated in array order.
11394- For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.