AGENTS.md

1# IME Composition
2 
3Scoped here rather than to the root `AGENTS.md` so it costs context only when you are working in
4the terminal input path. These rules also bind the chat composer and the mobile composer; if you are
5changing keyboard handling in those, read this file.
6 
7Each rule below was paid for by a shipped defect. The parenthetical is the issue that taught it.
8 
9- **Derive committed text from ranges and event data — never by diffing two observations of a mutable
10  buffer.** When the evidence is ambiguous, emit nothing. Diffing races the IME's own edits.
11 
12- **Match shortcuts on `event.code`, not `event.key`.** A CJK input source rewrites `key` while `code`
13  keeps the physical key: Cmd+C arrives as `{ key: "ㅊ", code: "KeyC" }`, and `Shift+T` typing ㅆ has
14  been misread as Enter. Use `@/lib/ime-latin-shortcut-key`. (#12171, #13033)
15 
16- **`keyCode === 229` means an IME owns the press.** Translating it races the IME's commit. Existing
17  guards in `terminal-jis-yen-input.ts` show the shape.
18 
19- **Guard above the key dispatch, not inside each key branch**, and guard `keyup` and global
20  `document` listeners too — a guard on `keydown` alone leaves the other edges unprotected.
21 
22- **`attachCustomKeyEventHandler` returning `false` does NOT call `preventDefault()`**, and it bypasses
23  xterm's `CompositionHelper` entirely. Pair the two deliberately.
24 
25- **Never normalize IME output at commit.** Normalize only at path handling and equality/search
26  comparison. Normalizing early destroys the distinction between conjoining and compatibility jamo.
27 
28- **Do not unmount a field with a composition in flight.** The OS aborts the composition, the text
29  returns as committed, and a resumed Hangul syllable degrades — 아 then ㄴ yields `아ㄴ`, never `안`.
30  Hiding is not a fix: `display:none` and `visibility:hidden` both blur the focused element and abort
31  it the same way. See `native-chat-composer-composition-hold.ts`. (#12118, STA-3219, #11332)
32 
33## Evidence bar for a change here
34 
35- **A recorded event-trace fixture** for the trace that motivated the change — not a hand-authored
36  event shape. Real IMEs produce sequences nobody guesses correctly; see
37  `tests/e2e/terminal-ime-observed-event-sequences.ts`.
38- **A paired negative** proving ordinary non-IME input is unchanged. It must be a genuine control:
39  an arm that dispatches `compositionupdate` is a Latin *preedit*, not ordinary input.
40- **A mutation check.** Removing or bypassing the fix must make the positive fail while the negative
41  passes. A test that survives deleting the code it guards is guarding nothing.
42