From dbeecb11bee72c39ba0e6837b7e8812c629fdb0e Mon Sep 17 00:00:00 2001
From: Neil <4138956+nwparker@users.noreply.github.com>
Date: Thu, 6 Aug 2026 08:49:38 -0700
Subject: [PATCH] docs(terminal): record that the swallow eats a keystroke
 after Japanese conversion
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This pin framed the swallowed insertText around Cmd interrupting a
composition. A differential through Japanese multi-segment conversion shows
it is broader: type a segment, convert, then press `a`, and the `a` is
lost. No modifier, no exotic gesture. Korean surfaced it first only because
2-Set composes on nearly every keystroke.

Also records why it cannot simply be fixed. The suppression de-duplicates
IMEs that deliver their commit a task after compositionend, which a sibling
test pins; this swallow is that dedup's false positive, and the two events
differ only in payload, so no flag-timing change separates them. Both a
smaller redesign and a content-aware variant were built and measured — the
first duplicates on IBus, the second costs a reported row's test and is
blocked while the patch cannot be regenerated.

The Japanese arrays behind this are authored, not observed: no Japanese DOM
composition trace exists in the corpus.
---
 ...e-xterm-composition-commit-overlap.test.ts | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/renderer/src/components/terminal-pane/terminal-ime-xterm-composition-commit-overlap.test.ts b/src/renderer/src/components/terminal-pane/terminal-ime-xterm-composition-commit-overlap.test.ts
index 664acd2bf70..ce51f4f87b8 100644
--- a/src/renderer/src/components/terminal-pane/terminal-ime-xterm-composition-commit-overlap.test.ts
+++ b/src/renderer/src/components/terminal-pane/terminal-ime-xterm-composition-commit-overlap.test.ts
@@ -21,6 +21,26 @@
 //    the timer cleared _pendingCompositionStart; handleCompositionInput passes the first
 //    check, then reads the cleared sentinel and substitutes '' for the data.
 //
+//    THIS IS BROADER THAN THE Cmd FRAMING ABOVE. A differential run through Japanese
+//    multi-segment conversion found shipped behaviour swallows an ordinary Latin key
+//    typed one macrotask after a conversion commit: type a segment, convert, then press
+//    `a`, and the `a` is lost. No modifier, no exotic gesture — every Japanese user who
+//    keeps typing straight after converting. Korean surfaced it first only because
+//    2-Set composes on nearly every keystroke.
+//
+//    The suppression is NOT a defect on its own: it de-duplicates IMEs that deliver
+//    their commit insertText a task after compositionend (IBus, Mozc), which
+//    terminal-stock-composition.test.ts pins. This swallow is that dedup's false
+//    positive. The two events are structurally identical — same inputType, same
+//    composed, same preceding 229 keydown — and differ only in payload, so no
+//    flag-timing change separates them. A redesign was built and measured: it fixes
+//    this and duplicates on IBus. A content-aware variant fixes both at +5 lines but
+//    flips a reported row's test, and is blocked regardless while the patch cannot be
+//    regenerated. See .tmp/ime-handoff/swarm-scratch/lane-group-e-redesign/.
+//
+//    The Japanese arrays in that differential are EXPLICITLY AUTHORED, not observed —
+//    no Japanese DOM composition trace exists in this corpus.
+//
 // Four things a future reader must not misread:
 //   1. No reporter has filed either of these. #12164 was considered and rejected: its
 //      comment 1 is untyped agent OUTPUT doubling on the wide-glyph repaint path, and