From 3a84fa7c3bbd1374ebdb47c6d0bbd83c3272b949 Mon Sep 17 00:00:00 2001 From: viktorce Date: Thu, 19 Nov 2026 23:02:17 +0000 Subject: [PATCH] fix(terminal): a clear partway through a control sequence no longer leaves stray characters on screen A control sequence can reach a client in two pieces of output. When a `cleared` event arrived between them, the client appended the erase text ESC[H ESC[2J ESC[3J to the terminal's output. The ESC that starts it made the emulator abandon the sequence it was reading and draw the rest as text. A cursor-position query, ESC[6n, split around a clear put a stray "n" on the screen and was never answered. A colour change, ESC[31m, put a stray "m" there and lost the colour. clearOutput now sends the start of the unfinished sequence again after the erase, so the rest completes it on the cleared screen. A new contracts helper, unfinishedTerminalSequence, finds that start from the last ESC with the shared parser model. It leaves out C0 controls that arrived inside an escape or CSI sequence, because the emulator already ran them. With no sequence open a clear sends the same bytes as before. The text fallback still starts empty after a clear. A string that a program never ends, such as an OSC with no terminator, now stays open across a clear, where the erase text used to end it. When later output trims the buffer inside such a string, the text fallback hides the rest of it, as it already did with no clear. Three cases get worse. A clear stores an open string again, so the next output can evict older output, including output that set modes. On a server that still drops queued output at a clear, the reopened sequence takes its ending from whatever comes next, so ESC[6 with a dropped "n" and then "hello" shows "ello". An OSC query gets one extra reply for each clear that lands after a complete query inside the string. --- apps/web/src/terminal/ghostty/core.test.ts | 39 +++++++++++++++++++ .../src/state/terminalOutput.ts | 12 +++--- .../src/state/terminalSession.test.ts | 29 ++++++++++++++ packages/contracts/src/terminal.test.ts | 17 ++++++++ packages/contracts/src/terminal.ts | 24 ++++++++++++ 5 files changed, 116 insertions(+), 5 deletions(-) diff --git a/apps/web/src/terminal/ghostty/core.test.ts b/apps/web/src/terminal/ghostty/core.test.ts index 6af90ada529df..e14868c13f0ec 100644 --- a/apps/web/src/terminal/ghostty/core.test.ts +++ b/apps/web/src/terminal/ghostty/core.test.ts @@ -534,6 +534,45 @@ describe("GhosttyTerminalCore snapshots", () => { expect(modes()).toEqual(live); }); + + it.each([ + // The shell's cursor-position query, ESC[6n. + { name: "a query", start: "\x1b[6", rest: "n" }, + // A window title, which runs until its BEL. + { name: "a title string", start: "\x1b]0;ti", rest: "tle\x07" }, + ])("completes a control sequence that a clear splits ($name)", async ({ start, rest }) => { + const replies: string[] = []; + const referenceReplies: string[] = []; + const [core, reference] = await Promise.all([ + createCore((data) => replies.push(data)), + createCore((data) => referenceReplies.push(data)), + ]); + let state = createSession(""); + const initial = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR); + writeTerminalOutputUpdate(core, initial); + let cursor = initial.cursor; + const apply = (next: TerminalBufferState) => { + state = next; + const update = readTerminalOutputUpdate(state.output, cursor); + writeTerminalOutputUpdate(core, update); + cursor = update.cursor; + }; + + apply(append(state, `before${start}`)); + apply( + applyTerminalAttachStreamEvent(state, { + type: "cleared", + threadId: "terminal-stream-test", + terminalId: "term-1", + }), + ); + apply(append(state, `${rest}after`)); + + // An empty screen that got the sequence in one piece. + reference.write(`${start}${rest}after`); + expect(core.snapshot()).toEqual(reference.snapshot()); + expect(replies).toEqual(referenceReplies); + }); }); describe("GhosttyTerminalCore scrollback", () => { diff --git a/packages/client-runtime/src/state/terminalOutput.ts b/packages/client-runtime/src/state/terminalOutput.ts index e01785bc30f11..d686fca764756 100644 --- a/packages/client-runtime/src/state/terminalOutput.ts +++ b/packages/client-runtime/src/state/terminalOutput.ts @@ -3,6 +3,7 @@ import { TERMINAL_SEQUENCE_GROUND, terminalSequenceEnd, terminalSequenceStateAfter, + unfinishedTerminalSequence, } from "@t3tools/contracts"; export interface TerminalOutputChunk { @@ -280,13 +281,14 @@ const CLEAR_TERMINAL_TEXT = "\u001b[H\u001b[2J\u001b[3J"; /** Earlier output stays retained so a replay from the start restores those modes. */ function clearOutput(current: TerminalOutputState, maxBufferBytes: number): TerminalOutputState { - // The erase rides over the budget: trimming here would evict the output that set those modes. + // The erase's ESC makes an emulator abandon a control sequence it is partway through and draw + // the rest as text, so the start of that sequence is sent again after the erase. + const open = unfinishedTerminalSequence(current.chunks.map((chunk) => chunk.data).join("")); + // Both ride over the budget: trimming here would evict the output that set those modes. const cleared = appendOutput( current, - CLEAR_TERMINAL_TEXT, - maxBufferBytes <= 0 - ? maxBufferBytes - : Math.max(maxBufferBytes, current.retainedBytes + CLEAR_TERMINAL_TEXT.length), + `${CLEAR_TERMINAL_TEXT}${open}`, + maxBufferBytes <= 0 ? maxBufferBytes : Number.POSITIVE_INFINITY, ); return { ...cleared, textStartOffset: cleared.nextOffset }; } diff --git a/packages/client-runtime/src/state/terminalSession.test.ts b/packages/client-runtime/src/state/terminalSession.test.ts index d4e850b9c8b0a..455721d8bea00 100644 --- a/packages/client-runtime/src/state/terminalSession.test.ts +++ b/packages/client-runtime/src/state/terminalSession.test.ts @@ -15,6 +15,7 @@ import { INITIAL_TERMINAL_OUTPUT_CURSOR, nextTerminalAttachSeedState, readTerminalOutputUpdate, + terminalOutputReplay, terminalOutputText, } from "./terminalSession.ts"; @@ -352,6 +353,34 @@ describe("terminal session reducers", () => { expect(state.lifecycleVersion).toBe(2); }); + it("sends the start of an unfinished control sequence again after the erase", () => { + const erase = "\u001b[H\u001b[2J\u001b[3J"; + const open = "\u001b]0;é"; + // A full 16-byte buffer that ends partway through a title string that came in two outputs. + let state = EMPTY_TERMINAL_BUFFER_STATE; + for (const data of ["0123456789\u001b]0;", "é"]) { + state = applyTerminalAttachStreamEvent( + state, + { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data }, + 16, + ); + } + const cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor; + + state = applyTerminalAttachStreamEvent( + state, + { type: "cleared", threadId: TARGET.threadId, terminalId: TARGET.terminalId }, + 16, + ); + expect(readTerminalOutputUpdate(state.output, cursor)).toMatchObject({ + type: "append", + data: `${erase}${open}`, + }); + // An older mobile binary recreates its emulator unless the new replay extends the last one. + expect(terminalOutputReplay(state.output)).toBe(`0123456789${open}${erase}${open}`); + expect(terminalOutputText(state.output)).toBe(""); + }); + it("does not reuse a renderer cursor when a fresh attach has matching counters", () => { const first = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), { type: "snapshot", diff --git a/packages/contracts/src/terminal.test.ts b/packages/contracts/src/terminal.test.ts index 16b3ed1d38eb9..10b5b41172165 100644 --- a/packages/contracts/src/terminal.test.ts +++ b/packages/contracts/src/terminal.test.ts @@ -8,6 +8,7 @@ import { TerminalError, TerminalOpenInput, TerminalProviderEnvironmentError, + unfinishedTerminalSequence, } from "./terminal.ts"; import { ProviderInstanceId } from "./providerInstance.ts"; @@ -71,3 +72,19 @@ describe("chunkTerminalWrite", () => { expect(chunks.join("")).toBe(data); }); }); + +describe("unfinishedTerminalSequence", () => { + it.each([ + { name: "a query after a finished colour change", text: "a\x1b[31mb\x1b[6", open: "\x1b[6" }, + { name: "text after a finished sequence", text: "a\x1b[31mb", open: "" }, + { name: "text with no ESC", text: "]abc", open: "" }, + { name: "an ESC alone", text: "ab\x1b", open: "\x1b" }, + // A terminal runs these controls when they arrive, so they are not sent again. + { name: "a CSI holding a space and a line feed", text: "\x1b[2 \n", open: "\x1b[2 " }, + { name: "an escape holding a tab and a backspace", text: "\x1b\t(\b", open: "\x1b(" }, + { name: "a title string holding a line feed", text: "\x1b]0;a\nb", open: "\x1b]0;a\nb" }, + { name: "an ended title string", text: "\x1b]0;a\x07", open: "" }, + ])("returns the open sequence after $name", ({ text, open }) => { + expect(unfinishedTerminalSequence(text)).toBe(open); + }); +}); diff --git a/packages/contracts/src/terminal.ts b/packages/contracts/src/terminal.ts index 09678600764b2..7bc7ac6e87644 100644 --- a/packages/contracts/src/terminal.ts +++ b/packages/contracts/src/terminal.ts @@ -97,6 +97,30 @@ export function terminalSequenceEnd(state: number, text: string): number { return index; } +/** + * The unfinished control sequence `text` ends in, as text that takes a terminal in ground state + * back to the same point, or "" when `text` ends outside a sequence or lacks that sequence's ESC. + * It leaves out the C0 controls inside an escape or CSI sequence, which a terminal runs on arrival. + */ +export function unfinishedTerminalSequence(text: string): string { + const escape = text.lastIndexOf("\u001b"); + if (escape < 0) return ""; + const kept: string[] = []; + let keptStart = escape; + let state = SEQUENCE_ESCAPE; + for (let index = escape + 1; index < text.length; index += 1) { + const unit = text.charCodeAt(index); + if (unit < 0x20 && (state & 7) <= SEQUENCE_CSI) { + kept.push(text.slice(keptStart, index)); + keptStart = index + 1; + } + state = nextTerminalSequenceState(state, unit); + if (state === TERMINAL_SEQUENCE_GROUND) return ""; + } + kept.push(text.slice(keptStart)); + return kept.join(""); +} + /** * The final `maxBytes` of UTF-8 a client retains, starting at a code point boundary and * outside any control sequence the cut went through.