Files
Netcatty/components/terminal/runtime/terminalImeTextInput.test.ts
T
bincxz 5ad4eaa309 fix(terminal): only rewrite IME sentinel keyups to the deferred key
A real keyup for another held key could land while the punctuation deferral
was still armed (the deferred key's own release was swallowed). That release
was rewritten to the deferred physical key, so in Kitty report-event modes the
held key's forwarded press never got its release and the TUI saw it stuck down
until focus loss or session reset.

Restrict the rewrite to IME sentinel releases (Process/229/Unidentified/
Dead/Compose, mirroring the non-text DOM keys the Kitty encoder already
refuses to send as text). Any real release still ends the stale deferral, so
the #3103 recovery is unchanged.
2026-08-27 13:11:13 +08:00

448 lines
16 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import {
isAsciiPunctuationKey,
isUnchangedDeferredImeTextInput,
shouldBlockKeyPressForImeTextInput,
shouldCommitDeferredImeTextInput,
shouldDeferKeyDownForImeTextInput,
shouldFlushDeferredImeTextInputOnKeyUp,
shouldFlushStaleDeferredImeTextInput,
shouldRewriteKeyUpToDeferredImeKey,
} from "./terminalImeTextInput";
const runtimeSource = readFileSync(
join(dirname(fileURLToPath(import.meta.url)), "createXTermRuntime.ts"),
"utf8",
);
test("isAsciiPunctuationKey accepts common remappable punctuation", () => {
for (const key of [",", ".", "/", ";", "'", "[", "]", "\\", "-", "=", "`", "?", "!", ":", '"', "<", ">", "{", "}", "|", "_", "+", "~", "@", "#", "$", "%", "^", "&", "*", "(", ")"]) {
assert.equal(isAsciiPunctuationKey(key), true, key);
}
});
test("isAsciiPunctuationKey rejects letters, digits, space, and CJK", () => {
for (const key of ["a", "Z", "0", " ", ",", "、", "?", "Enter", "ArrowLeft"]) {
assert.equal(isAsciiPunctuationKey(key), false, key);
}
});
test("shouldDeferKeyDownForImeTextInput defers bare ASCII punctuation keydowns", () => {
assert.equal(
shouldDeferKeyDownForImeTextInput({ type: "keydown", key: ",", keyCode: 188 }),
true,
);
assert.equal(
shouldDeferKeyDownForImeTextInput({ type: "keydown", key: "?", keyCode: 191 }),
true,
);
});
test("shouldDeferKeyDownForImeTextInput leaves composition and modified keys alone", () => {
assert.equal(
shouldDeferKeyDownForImeTextInput({ type: "keydown", key: ",", keyCode: 229 }),
false,
);
assert.equal(
shouldDeferKeyDownForImeTextInput({ type: "keydown", key: ",", isComposing: true }),
false,
);
assert.equal(
shouldDeferKeyDownForImeTextInput({ type: "keydown", key: ",", ctrlKey: true }),
false,
);
assert.equal(
shouldDeferKeyDownForImeTextInput({ type: "keydown", key: "a", keyCode: 65 }),
false,
);
assert.equal(
shouldDeferKeyDownForImeTextInput({ type: "keypress", key: "," }),
false,
);
});
test("shouldBlockKeyPressForImeTextInput only while a deferral is armed", () => {
assert.equal(
shouldBlockKeyPressForImeTextInput(",", { type: "keypress", key: "," }),
true,
);
assert.equal(
shouldBlockKeyPressForImeTextInput(null, { type: "keypress", key: "," }),
false,
);
assert.equal(
shouldBlockKeyPressForImeTextInput(",", { type: "keydown", key: "," }),
false,
);
});
test("shouldBlockKeyPressForImeTextInput still blocks the deferred keystroke itself", () => {
assert.equal(
shouldBlockKeyPressForImeTextInput(
"/",
{ type: "keypress", key: "/", keyCode: 191 },
191,
),
true,
);
// Shift+/ reports "?" on keydown, so the deferral arms with "?".
assert.equal(
shouldBlockKeyPressForImeTextInput(
"?",
{ type: "keypress", key: "?", keyCode: 191 },
191,
),
true,
);
assert.equal(
shouldBlockKeyPressForImeTextInput(
"/",
{ type: "keypress", key: "/", isComposing: true },
191,
),
true,
);
});
test("a stale deferral must not swallow unrelated keypresses (#3103)", () => {
// Uppercase letters are routed through keypress by xterm, so a blanket
// keypress block turned one stale deferral into a terminal that ignored
// everything typed afterwards.
assert.equal(
shouldBlockKeyPressForImeTextInput(
"/",
{ type: "keypress", key: "X", keyCode: 88 },
191,
),
false,
);
assert.equal(
shouldBlockKeyPressForImeTextInput(
"/",
{ type: "keypress", key: "a", keyCode: 65 },
191,
),
false,
);
// A matching keyCode keeps the block when an IME rewrites the key label.
assert.equal(
shouldBlockKeyPressForImeTextInput(
"/",
{ type: "keypress", key: "1", keyCode: 191 },
191,
),
true,
);
});
test("a Windows IME release reporting Process must flush the deferred slash (#3103)", () => {
// Windows + CJK IME in vi: keydown still reports the physical key while the
// IME consumes it, then reports Process/229 on the release and never sends
// an insertText the runtime would treat as a remap.
let deferredKey: string | null = null;
const keydown = { type: "keydown", key: "/", keyCode: 191 };
if (shouldDeferKeyDownForImeTextInput(keydown)) deferredKey = keydown.key;
assert.equal(deferredKey, "/");
const release = { type: "keyup", key: "Process", keyCode: 229 };
if (shouldFlushDeferredImeTextInputOnKeyUp(deferredKey, release)) deferredKey = null;
assert.equal(deferredKey, null, "the deferral must not outlive its keystroke");
// Input keeps flowing afterwards.
assert.equal(
shouldBlockKeyPressForImeTextInput(deferredKey, { type: "keypress", key: "x", keyCode: 88 }),
false,
);
});
test("a held key released while the deferral is armed keeps its own keyup identity", () => {
// "/" is deferred (its own release was swallowed) and the user still holds
// "a" with the other hand, so the "a" keyup lands first. The stale deferral
// still ends, but that release is a real keyup, not an IME sentinel: only
// the deferred punctuation key may be rewritten, otherwise the held key's
// press entry is never paired and the TUI sees it stuck down.
const deferredKey = "/";
const heldKeyUp = { type: "keyup", key: "a", keyCode: 65 };
assert.equal(
shouldFlushDeferredImeTextInputOnKeyUp(deferredKey, heldKeyUp),
true,
"the stale deferral still ends on a real release",
);
assert.equal(
shouldRewriteKeyUpToDeferredImeKey(deferredKey, heldKeyUp),
false,
"an unrelated release must not be rewritten to the deferred key",
);
});
test("only IME sentinel releases are rewritten to the deferred key", () => {
// Windows IMEs report Process/229 (occasionally Unidentified) as the release
// of a key they consumed — those are the only releases that stand in for the
// deferred punctuation key.
assert.equal(
shouldRewriteKeyUpToDeferredImeKey("/", { type: "keyup", key: "Process", keyCode: 229 }),
true,
);
assert.equal(
shouldRewriteKeyUpToDeferredImeKey("/", { type: "keyup", key: "Unidentified" }),
true,
);
assert.equal(
shouldRewriteKeyUpToDeferredImeKey("/", { type: "keyup", key: "/", keyCode: 191 }),
false,
"a matched release already encodes from the real event",
);
assert.equal(
shouldRewriteKeyUpToDeferredImeKey("/", { type: "keyup", key: "Shift", keyCode: 16 }),
false,
);
assert.equal(
shouldRewriteKeyUpToDeferredImeKey("/", { type: "keyup", key: "a", keyCode: 65, ctrlKey: true }),
false,
);
assert.equal(
shouldRewriteKeyUpToDeferredImeKey(null, { type: "keyup", key: "Process", keyCode: 229 }),
false,
);
});
test("a deferral left without release or insertText recovers on the next keystroke (#3103)", () => {
let deferredKey: string | null = null;
const keydown = { type: "keydown", key: "/", keyCode: 191 };
if (shouldDeferKeyDownForImeTextInput(keydown)) deferredKey = keydown.key;
assert.equal(deferredKey, "/");
// No insertText and no keyup at all; the user then types a plain letter.
const nextKeyDown = { type: "keydown", key: "a", keyCode: 65 };
if (shouldFlushStaleDeferredImeTextInput(deferredKey, nextKeyDown)) deferredKey = null;
assert.equal(deferredKey, null, "the stale deferral must flush before the new keystroke");
assert.equal(
shouldBlockKeyPressForImeTextInput(deferredKey, { type: "keypress", key: "a", keyCode: 65 }),
false,
);
});
test("auto-repeat and modifier keystrokes keep the deferral armed", () => {
// Same-key keydown is auto-repeat: re-arm instead of flushing, so a held key
// does not emit an extra character per repeat.
assert.equal(
shouldFlushStaleDeferredImeTextInput("/", { type: "keydown", key: "/", keyCode: 191 }),
false,
);
assert.equal(
shouldFlushStaleDeferredImeTextInput("/", { type: "keydown", key: "Shift", keyCode: 16 }),
false,
);
assert.equal(
shouldFlushStaleDeferredImeTextInput("/", {
type: "keydown",
key: "c",
keyCode: 67,
ctrlKey: true,
}),
false,
);
assert.equal(
shouldFlushStaleDeferredImeTextInput("/", {
type: "keydown",
key: "d",
keyCode: 229,
isComposing: true,
}),
false,
);
assert.equal(
shouldFlushDeferredImeTextInputOnKeyUp("/", { type: "keyup", key: "Shift", keyCode: 16 }),
false,
);
assert.equal(
shouldFlushDeferredImeTextInputOnKeyUp("/", {
type: "keyup",
key: "c",
keyCode: 67,
ctrlKey: true,
}),
false,
);
});
test("an active composition still resolves the deferred keystroke via insertText", () => {
// The IME absorbed the punctuation into a composition: the composing release
// must not flush the ASCII key ahead of the committed glyph.
assert.equal(
shouldFlushDeferredImeTextInputOnKeyUp("/", {
type: "keyup",
key: "/",
keyCode: 191,
isComposing: true,
}),
false,
);
assert.equal(
shouldCommitDeferredImeTextInput("/", { inputType: "insertText", data: "、" }),
true,
);
});
test("a matched keyup still flushes the English punctuation fallback (#2833)", () => {
assert.equal(
shouldFlushDeferredImeTextInputOnKeyUp("/", { type: "keyup", key: "/", keyCode: 191 }),
true,
);
assert.equal(
shouldFlushDeferredImeTextInputOnKeyUp(null, { type: "keyup", key: "/", keyCode: 191 }),
false,
);
assert.equal(
shouldFlushDeferredImeTextInputOnKeyUp("/", { type: "keydown", key: "/", keyCode: 191 }),
false,
);
});
test("shouldCommitDeferredImeTextInput accepts insertText payloads while deferred", () => {
assert.equal(
shouldCommitDeferredImeTextInput(",", { inputType: "insertText", data: "," }),
true,
);
assert.equal(
shouldCommitDeferredImeTextInput(",", { inputType: "insertText", data: "," }),
true,
);
assert.equal(
shouldCommitDeferredImeTextInput(null, { inputType: "insertText", data: "," }),
false,
);
assert.equal(
shouldCommitDeferredImeTextInput(",", { inputType: "insertFromPaste", data: "," }),
false,
);
assert.equal(
shouldCommitDeferredImeTextInput(",", { inputType: "insertText", data: null }),
false,
);
});
test("isUnchangedDeferredImeTextInput detects English punctuation flush", () => {
assert.equal(isUnchangedDeferredImeTextInput(",", ","), true);
assert.equal(isUnchangedDeferredImeTextInput(",", ","), false);
assert.equal(isUnchangedDeferredImeTextInput(null, ","), false);
});
test("createXTermRuntime defers ASCII punctuation keydowns to insertText", () => {
assert.match(runtimeSource, /shouldDeferKeyDownForImeTextInput\(e\)/);
assert.match(runtimeSource, /armImeTextInputDeferral\(e\)/);
assert.match(
runtimeSource,
/shouldBlockKeyPressForImeTextInput\(\s*imeTextInputDeferredKey,\s*e,\s*imeTextInputDeferredKittyEvent\?\.keyCode \?\? null,\s*\)/,
);
assert.match(
runtimeSource,
/shouldCommitDeferredImeTextInput\(imeTextInputDeferredKey, event\)/,
);
assert.match(runtimeSource, /commitImeTextInput\(event\.data\)/);
assert.match(runtimeSource, /isUnchangedDeferredImeTextInput\(deferredKey, text\)/);
assert.match(runtimeSource, /imeTextInputDeferredKittyEvent/);
// Manual commit bypasses xterm onUserInput; clear selection unless preserved.
assert.match(
runtimeSource,
/!ctx\.terminalSettingsRef\.current\?\.preserveSelectionOnInput/,
);
assert.match(runtimeSource, /term\.clearSelection\(\)/);
const clearSelIdx = runtimeSource.indexOf("term.clearSelection()");
const commitIdx = runtimeSource.indexOf("const commitImeTextInput = (text: string)");
const firstHandleIdx = runtimeSource.indexOf(
"handleTerminalInputData",
commitIdx,
);
assert.ok(
commitIdx >= 0 &&
clearSelIdx > commitIdx &&
firstHandleIdx > clearSelIdx,
);
// Must run before Kitty/xterm send the half-width key from keydown.
const deferIdx = runtimeSource.indexOf("shouldDeferKeyDownForImeTextInput(e)");
const kittySendIdx = runtimeSource.indexOf("if (kittySequenceForKeyDown)");
assert.ok(deferIdx >= 0 && kittySendIdx > deferIdx);
// Unchanged ASCII must encode via Kitty key events, not composition text.
const unchangedIdx = runtimeSource.indexOf("isUnchangedDeferredImeTextInput(deferredKey, text)");
const compositionIdx = runtimeSource.indexOf(
"encodeKittyCompositionText(kittyKeyboardMode, text)",
);
assert.ok(unchangedIdx >= 0 && compositionIdx > unchangedIdx);
// Even when the source writes the literal glyph, broadcast peers still get
// the deferred physical key (with legacy fallback), not composition text.
const armIdx = runtimeSource.indexOf("const armImeTextInputDeferral");
assert.ok(armIdx >= 0);
const armSlice = runtimeSource.slice(armIdx, armIdx + 700);
assert.match(
armSlice,
/imeTextInputDeferredKittyEvent = toKittyKeyboardEvent\(event\)/,
);
assert.doesNotMatch(
armSlice,
/imeTextInputDeferredKittyEvent = kittyKeyboardProtocolEnabled/,
);
const unchangedFallbackIdx = runtimeSource.indexOf(
"isUnchangedDeferredImeTextInput(deferredKey, text))",
unchangedIdx + 1,
);
assert.ok(unchangedFallbackIdx > unchangedIdx);
assert.match(
runtimeSource.slice(unchangedFallbackIdx, unchangedFallbackIdx + 1800),
/handleTerminalInputData\(text\);[\s\S]*shouldTrackKittyKeyRelease\(kittyKeyboardMode, pressEvent\)[\s\S]*upsertKittyKeyboardForwardedPress\(\s*kittyForwardedKeys,[\s\S]*broadcastKittyInput\(\{[\s\S]*kind: "key",[\s\S]*fallbackToLegacy: true,/,
);
// Remap path must fall back to literal text when composition encoding is null
// (report-all without associated text).
assert.match(
runtimeSource.slice(compositionIdx, compositionIdx + 420),
/if \(encoded\) \{[\s\S]*handleTerminalInputData\(encoded, \{ source: "kitty" \}\);[\s\S]*\} else \{[\s\S]*handleTerminalInputData\(text\);/,
);
});
test("createXTermRuntime recovers a stuck IME punctuation deferral (#3103)", () => {
// Any real key release ends the deferral, not just an exact key match.
const keyupIdx = runtimeSource.indexOf('if (e.type === "keyup")');
assert.ok(keyupIdx >= 0);
const keyupSlice = runtimeSource.slice(keyupIdx, keyupIdx + 2000);
assert.match(
keyupSlice,
/shouldFlushDeferredImeTextInputOnKeyUp\(imeTextInputDeferredKey, e\)/,
);
assert.match(keyupSlice, /flushImeTextInputDeferral\(\);/);
// Only an IME sentinel release (Process/229/Unidentified) may be rewritten
// to the deferred physical key; an unrelated keyup keeps its own identity so
// the held key's forwarded press still gets its release.
assert.match(
keyupSlice,
/shouldRewriteKeyUpToDeferredImeKey\(imeTextInputDeferredKey, e\)/,
);
assert.match(
keyupSlice,
/\.\.\.deferredKittyEvent,\s*type: "keyup",/,
);
const kittyReleaseIdx = keyupSlice.indexOf("toKittyKeyboardEvent(releaseEvent)");
assert.ok(kittyReleaseIdx > keyupSlice.indexOf("flushImeTextInputDeferral();"));
// The stale flush runs on keydown, after the broadcast guard and before the
// composition handling, so a wedged deferral cannot survive a new keystroke.
const staleIdx = runtimeSource.indexOf(
"shouldFlushStaleDeferredImeTextInput(imeTextInputDeferredKey, e)",
);
assert.ok(staleIdx > keyupIdx);
const keydownGuardIdx = runtimeSource.indexOf("if (handlingKittyBroadcast) return true;", keyupIdx);
const keyCode229Idx = runtimeSource.indexOf("if (e.keyCode === 229) {", keyupIdx);
assert.ok(
keydownGuardIdx > keyupIdx &&
staleIdx > keydownGuardIdx &&
keyCode229Idx > staleIdx,
);
assert.match(
runtimeSource.slice(staleIdx - 400, staleIdx + 200),
/flushImeTextInputDeferral\(\);/,
);
});