Files
Netcatty/components/terminal/runtime/shiftEnterText.test.ts
T
GOUKI9999andClaude Opus 5.5 e3894eb850 terminal: allow Shift+Enter text fallback inside ConPTY Win32 input mode (#3464)
* terminal: allow Shift+Enter text inside ConPTY Win32 input mode

Win32 input mode (PR #3247) delivers Shift+Enter to ConPTY as a lossless
INPUT_RECORD, which CLIs reading console records natively (Codex, Grok) can
use. Node/Bun CLIs read input through libuv, which drops modifier state when
translating INPUT_RECORD to VT bytes, so Claude Code and CodeBuddy still see a
bare CR and submit instead of inserting a newline (anthropics/claude-code#92771,
reproducing on 2.1.278).

While the mode is active, Netcatty also skips its Shift+Enter text fallback and
Kitty encoding, so shiftEnterNewlineText had no effect on local Windows
sessions at all.

Add shiftEnterForceText (default false): when enabled, Shift+Enter sends the
configured text even inside Win32 input mode, and consumes the keydown so no
native record is emitted as well. Add `\e` (ESC) to the escape decoder so the
text can carry the legacy Alt+Enter encoding, which is the only sequence that
survives the ConPTY input path.

Defaults keep the #2974 behaviour untouched for Codex/Grok.

* docs: record libuv input findings and the Win32 input mode opt-out

* fix(terminal): don't swallow Shift+Enter when there is no text to send

The Shift+Enter send-text interception resolved its text after already
calling preventDefault/stopPropagation, and returned false outside the
`if (shiftEnterText)` guard. When resolveShiftEnterText() yields an empty
string (e.g. a persisted empty setting) the keydown was therefore consumed
with nothing written, and the handler never fell through to the Win32
bookkeeping or Kitty paths below, so no Enter reached the session either.
The result was indistinguishable from a dead feature.

Resolve the text first and only enter the interception block when it is
non-empty; empty text now falls through exactly as it did before the
`shiftEnterForceText` setting existed, so a normal Enter is still produced.
The opt-out semantics for the non-empty case are unchanged.

Also tighten the source-shape test so it verifies the real intent: the
interception (preventDefault through return false) must live inside the
empty-text guard, which fails against the previous code.

* fix(terminal): scope Shift+Enter force-text to Win32 mode, honor it per broadcast target

Address review on #3464:

- The force-text opt-out could override a negotiated Kitty encoding that
  preserves Shift+Enter in non-Win32 sessions. The keydown decision now
  lives in shouldClaimShiftEnterForText: under Win32 input mode it follows
  shiftEnterForceText, otherwise only the existing collapse fallback
  applies. Covered by a regression test for a non-Win32 session whose Kitty
  encoding already preserves the chord.
- Broadcast Win32 targets returned the native record without consulting
  their own shiftEnterForceText. They now send their configured text for
  Shift+Enter when opted in, whether the source forwarded a key chord or a
  native Win32 record, and drop the paired release so ConPTY never sees a
  key-up without its key-down. Targets without the opt-out keep the native
  press/release pair. Tests cover source and target settings that differ.

ShiftEnterEvent now accepts KittyKeyboardEvent's optional type/modifier
fields so broadcast events can be checked with the same helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 23:36:10 +08:00

287 lines
13 KiB
TypeScript

import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import {
decodeTerminalTextEscapes,
doesKittyEncodingPreserveShiftEnter,
getShiftEnterSubmittedInput,
isBareShiftEnterLineEnding,
isShiftEnterLineContinuationText,
resolveShiftEnterText,
resolveWin32ForcedShiftEnterText,
SHIFT_ENTER_CSI_U_SEQUENCE,
shouldClaimShiftEnterForText,
shouldSendShiftEnterText,
} from "./shiftEnterText";
const keyEvent = (overrides: Partial<KeyboardEvent> = {}) => ({
type: "keydown",
key: "Enter",
shiftKey: true,
altKey: false,
ctrlKey: false,
metaKey: false,
isComposing: false,
...overrides,
}) as KeyboardEvent;
test("shift enter text defaults to newline", () => {
assert.equal(resolveShiftEnterText(), "\n");
});
test("shift enter text decodes newline, tab, carriage return, and backslash escapes", () => {
assert.equal(
decodeTerminalTextEscapes("line\\nnext\\tindent\\rreturn\\\\slash"),
"line\nnext\tindent\rreturn\\slash",
);
});
test("shift enter text decodes the escape escape as ESC", () => {
assert.equal(decodeTerminalTextEscapes("\\e\r"), "\u001b\r");
assert.equal(decodeTerminalTextEscapes("\\e[13;2u"), SHIFT_ENTER_CSI_U_SEQUENCE);
});
test("shift enter text can represent Tabby-style shell continuation", () => {
assert.equal(decodeTerminalTextEscapes(" \\\\\\n"), " \\\n");
});
test("shift enter continuation detection only matches backslash-newline endings", () => {
assert.equal(isShiftEnterLineContinuationText(" \\\n"), true);
assert.equal(isShiftEnterLineContinuationText(" \\\r\n"), true);
assert.equal(isShiftEnterLineContinuationText(" \\\r"), true);
assert.equal(isShiftEnterLineContinuationText("foo\n"), false);
assert.equal(isShiftEnterLineContinuationText("\r\n"), false);
});
test("shift enter submitted input detects single command text with a line ending", () => {
assert.deepEqual(getShiftEnterSubmittedInput("\n"), {
text: "",
lineEnding: "\n",
});
assert.deepEqual(getShiftEnterSubmittedInput("\r\n"), {
text: "",
lineEnding: "\r\n",
});
assert.deepEqual(getShiftEnterSubmittedInput("sudo whoami\n"), {
text: "sudo whoami",
lineEnding: "\n",
});
assert.equal(getShiftEnterSubmittedInput(" \\\n"), null);
assert.equal(getShiftEnterSubmittedInput("foo\nbar\n"), null);
});
test("shift enter handler only matches plain Shift+Enter keydown", () => {
assert.equal(shouldSendShiftEnterText(keyEvent()), true);
assert.equal(shouldSendShiftEnterText(keyEvent({ type: "keyup" })), false);
assert.equal(shouldSendShiftEnterText(keyEvent({ key: "NumpadEnter" })), false);
assert.equal(shouldSendShiftEnterText(keyEvent({ ctrlKey: true })), false);
assert.equal(shouldSendShiftEnterText(keyEvent({ metaKey: true })), false);
assert.equal(shouldSendShiftEnterText(keyEvent({ altKey: true })), false);
assert.equal(shouldSendShiftEnterText(keyEvent({ shiftKey: false })), false);
assert.equal(shouldSendShiftEnterText(keyEvent({ isComposing: true })), false);
});
test("shift enter handler respects the terminal setting toggle", () => {
assert.equal(
shouldSendShiftEnterText(keyEvent(), { shiftEnterNewlineEnabled: false }),
false,
);
});
test("bare line-ending Shift+Enter text is detected for TUI passthrough", () => {
assert.equal(isBareShiftEnterLineEnding("\n"), true);
assert.equal(isBareShiftEnterLineEnding("\r"), true);
assert.equal(isBareShiftEnterLineEnding("\r\n"), true);
assert.equal(isBareShiftEnterLineEnding(" \\\n"), false);
assert.equal(isBareShiftEnterLineEnding("sudo whoami\n"), false);
assert.equal(isBareShiftEnterLineEnding(""), false);
});
test("Kitty encodings that collapse Shift+Enter to CR/LF do not preserve the chord", () => {
assert.equal(doesKittyEncodingPreserveShiftEnter(null), false);
assert.equal(doesKittyEncodingPreserveShiftEnter(""), false);
assert.equal(doesKittyEncodingPreserveShiftEnter("\r"), false);
assert.equal(doesKittyEncodingPreserveShiftEnter("\n"), false);
assert.equal(doesKittyEncodingPreserveShiftEnter(SHIFT_ENTER_CSI_U_SEQUENCE), true);
});
test("force-text opt-out only overrides the Win32 hand-off", () => {
const forced = {
shiftEnterNewlineEnabled: true,
shiftEnterForceText: true,
};
const notForced = { ...forced, shiftEnterForceText: false };
// Regression: a negotiated Kitty encoding that preserves Shift+Enter (an
// SSH/TUI session outside ConPTY) must keep that encoding even when the
// Win32 opt-out is enabled.
assert.equal(
shouldClaimShiftEnterForText(keyEvent(), forced, {
win32InputMode: false,
kittySequenceForKeyDown: SHIFT_ENTER_CSI_U_SEQUENCE,
}),
false,
);
// Outside Win32 mode the existing collapse fallback is unchanged by the
// opt-out in either direction.
for (const settings of [forced, notForced]) {
for (const kittySequenceForKeyDown of ["\r", null]) {
assert.equal(
shouldClaimShiftEnterForText(keyEvent(), settings, {
win32InputMode: false,
kittySequenceForKeyDown,
}),
true,
);
}
}
// Win32 input mode keeps the native record unless the user opted out.
const win32 = { win32InputMode: true, kittySequenceForKeyDown: null };
assert.equal(shouldClaimShiftEnterForText(keyEvent(), notForced, win32), false);
assert.equal(shouldClaimShiftEnterForText(keyEvent(), forced, win32), true);
assert.equal(
shouldClaimShiftEnterForText(keyEvent(), { ...forced, shiftEnterNewlineEnabled: false }, win32),
false,
);
assert.equal(shouldClaimShiftEnterForText(keyEvent({ ctrlKey: true }), forced, win32), false);
});
test("Win32 forced Shift+Enter text requires the opt-out and non-empty text", () => {
const settings = {
shiftEnterNewlineEnabled: true,
shiftEnterNewlineText: "\\e\\r",
shiftEnterForceText: true,
};
assert.equal(resolveWin32ForcedShiftEnterText(keyEvent(), settings), "\u001b\r");
assert.equal(
resolveWin32ForcedShiftEnterText(keyEvent(), { ...settings, shiftEnterForceText: false }),
null,
);
assert.equal(
resolveWin32ForcedShiftEnterText(keyEvent(), { ...settings, shiftEnterNewlineText: "" }),
null,
);
assert.equal(resolveWin32ForcedShiftEnterText(keyEvent({ type: "keyup" }), settings), null);
});
test("runtime routes Shift+Enter text through the shared input handler", () => {
const source = readFileSync(
new URL("./createXTermRuntime.ts", import.meta.url),
"utf8",
);
assert.match(
source,
/const handleTerminalInputData = \(\s+data: string,\s+options\?: \{\s+source\?: "terminal" \| "shift-enter" \| "kitty";\s+[\s\S]*?skipBroadcast\?: boolean;\s+[\s\S]*?perCharacterWrites\?: boolean;\s+\},\s+\) => \{/s,
);
// Remap when Kitty encoding does not preserve Shift+Enter (not merely flags===0),
// skipping the ConPTY Win32 hand-off only when the force-text opt-out is on.
assert.match(
source,
/if \(\s*shouldClaimShiftEnterForText\(e, ctx\.terminalSettingsRef\.current, \{\s*win32InputMode: term\.modes\.win32InputMode,\s*kittySequenceForKeyDown,\s*\}\)\s*\) \{[\s\S]*?const shiftEnterText = resolveShiftEnterText\([\s\S]*?\)[\s\S]*?\}\s*if \(kittySequenceForKeyDown\)/s,
);
// The gate above only decides whether Shift+Enter is *eligible* for send-text.
// It must then claim the keydown only when resolveShiftEnterText() returned
// actual text: preventDefault/write/broadcast/return false all belong inside
// `if (shiftEnterText)`. Empty configured text falls through to the Win32 and
// Kitty paths below, so the press still yields a plain Enter instead of being
// consumed with nothing written — which looks like a dead feature.
const gateBlock = source.slice(
source.search(/shouldClaimShiftEnterForText\(e, ctx\.terminalSettingsRef\.current/),
source.indexOf("if (kittySequenceForKeyDown) {"),
);
const interceptionStart = gateBlock.indexOf("if (shiftEnterText) {");
assert.notEqual(interceptionStart, -1);
const interception = gateBlock.slice(interceptionStart);
assert.doesNotMatch(
gateBlock.slice(0, interceptionStart),
/e\.preventDefault\(\)|return false/,
);
assert.match(interception, /^if \(shiftEnterText\) \{\s*e\.preventDefault\(\);/);
assert.match(interception, /return false;\s*\}\s*\}\s*\}\s*$/);
assert.match(
source,
/shiftEnterForceText opts out of the Win32 hand-off for runtimes that/s,
);
assert.match(
source,
/vtExtensions: \{\s*win32InputMode: windowsPty\?\.backend === "conpty",\s*\},/s,
);
assert.match(
source,
/const kittySequenceForKeyDown =\s*!term\.modes\.win32InputMode &&\s*kittyKeyboardProtocolEnabled/s,
);
assert.match(
source,
/const shiftEnterText = resolveShiftEnterText\([\s\S]*?if \(shiftEnterText\) \{[\s\S]*?handleTerminalInputData\(shiftEnterText, \{\s*source: "shift-enter",\s*skipBroadcast: true,\s*\}\);\s*const forwarded = broadcastKittyInput\(\{\s*kind: "key",\s*event: kittyEvent,\s*fallbackToLegacy: true,\s*\}\);/s,
);
assert.match(
source,
/const canBroadcastInput = !sensitive &&[\s\S]*?const willBroadcastInput = canBroadcastInput && options\?\.skipBroadcast !== true;[\s\S]*?if \(!canBroadcastInput && !handlingKittyBroadcast\) \{\s*prepareSudoAutofillInput/s,
);
assert.match(
source,
/resolveOptions: \(\) => \(\{[\s\S]*?shiftEnterSettings: ctx\.terminalSettingsRef\.current,[\s\S]*?\}\),/s,
);
assert.doesNotMatch(source, /resolveShiftEnterText\([\s\S]*?alternateScreen:/s);
assert.match(source, /getShiftEnterSubmittedInput\(logicalData\)/);
assert.match(source, /inputSource !== "shift-enter"/);
assert.match(
source,
/if \(shouldSendShiftEnterText\(e, ctx\.terminalSettingsRef\.current\)\) \{\s+sudoAutofill\.cancelHint\(\);/s,
);
assert.match(
source,
/term\.onData\(\(data\) => \{[\s\S]*const sanitizedRawData = sanitizeTerminalInput\(data\);[\s\S]*handleTerminalInputData\(sanitizedRawData, \{\s*perCharacterWrites: shouldSplitRawPasteInputForWire\(sanitizedRawData\),?\s*\}\);\s+\}\);/,
);
assert.match(
source,
/const sanitizedData = sanitizeTerminalInput\(data\);[\s\S]*const encoded = term\.modes\.win32InputMode\s*\? null\s*:\s*encodeKittyCompositionText\(kittyKeyboardMode, sanitizedData\);[\s\S]*if \(encoded\) \{[\s\S]*handleTerminalInputData\(encoded, \{ source: "kitty" \}\);[\s\S]*\} else \{[\s\S]*handleTerminalInputData\(sanitizedData, \{\s*perCharacterWrites: shouldSplitImeTextInputForWire\(sanitizedData\),?\s*\}\);[\s\S]*broadcastKittyInput\(\{ kind: "text", text: sanitizedData \}\);/,
);
assert.match(
source,
/if \(term\.modes\.win32InputMode\) \{[\s\S]*win32InputModePendingEvent = \{\s*event: normalizedKittyEvent,\s*logicalData: resolveWin32InputLogicalData\(/s,
);
assert.match(
source,
/const broadcastInput: KittyKeyboardBroadcastInput = \{\s*kind: "win32",\s*data,\s*event: win32Input\.event,[\s\S]*handleTerminalInputData\(data, \{\s*logicalData: win32Input\.logicalData,\s*skipBroadcast: true,/s,
);
assert.match(
source,
/const hasForwardedWin32KeyDown = win32InputModeForwardedKeys\.delete\(identity\);[\s\S]*if \(term\.modes\.win32InputMode\) \{[\s\S]*releaseForwardedKittyPress\([\s\S]*if \(!hasForwardedWin32KeyDown\) \{[\s\S]*win32InputModePendingEvent = null;[\s\S]*return false;[\s\S]*logicalData: null,[\s\S]*return true;[\s\S]*releaseForwardedKittyPress/s,
);
assert.match(
source,
/if \(win32Input\.event\.type === "keydown"\) \{\s*upsertKittyKeyboardForwardedPress\(\s*win32InputModeForwardedKeys,\s*win32Input\.event\.code \|\| win32Input\.event\.key,\s*win32Input\.event,\s*\[\],/s,
);
assert.match(
source,
/if \(term\.modes\.win32InputMode\) \{[\s\S]*flushKittyKeyboardBroadcastReleases\(\s*win32InputModeForwardedKeys,[\s\S]*writeWin32InputModeEvent\(input\.event, null\);/s,
);
assert.match(source, /win32InputMode: term\.modes\.win32InputMode,/);
assert.match(
source,
/const win32BroadcastForwardedKeys = new Map<string, KittyKeyboardForwardedPress>\(\);/,
);
assert.match(
source,
/const forwardedPress = win32BroadcastForwardedKeys\.get\(identity\);[\s\S]*broadcastKittyInput\(\s*broadcastInput,\s*true,\s*forwardedPress\.targetSessionIds,/s,
);
assert.match(
source,
/upsertKittyKeyboardForwardedPress\(\s*win32BroadcastForwardedKeys,[\s\S]*forwarded\.targetSessionIds,/s,
);
assert.match(source, /ctx\.container\.addEventListener\("input", markKittyTextInput, true\);/);
assert.match(
source,
/if \(shouldMarkKittyTextInputEvent\(event\)\) markKittyCompositionPending\(true\);/,
);
assert.match(
source,
/flushKittyKeyboardBroadcastReleases\(\s+kittyForwardedKeys,[\s\S]*encodeKittyKeyEvent\(kittyKeyboardMode, input\.event\)[\s\S]*handleTerminalInputData\(sequence, \{ source: "kitty" \}\)/,
);
assert.doesNotMatch(source, /writeToSession\(id, textToSend\)/);
});