Files
Netcatty/components/terminal/runtime/cursorLineHighlight.test.ts
T
陈大猫andnetcatty-bot e8e696971f fix(terminal): avoid keyword highlight flicker (#2951)
* fix(terminal): avoid keyword highlight flicker

* fix: address Codex review on PR #2951

* fix: address Codex review on PR #2951

* perf(terminal): defer highlight catch-up under load

* perf(terminal): bound deferred highlight work

* fix(terminal): bound highlight catch-up backlog

* fix(terminal): mirror history wipes in highlighter

* fix(ci): load throughput baseline from PR base

* fix(terminal): preserve highlight rebuild ordering

* fix(terminal): drain highlights before exit capture

* fix(terminal): preserve line state across clear

* perf(terminal): slice history serialization

* fix(terminal): preserve parser state on recolor

* fix(terminal): preserve protocol state on recolor

* fix(terminal): retain live state during recolor

* fix(terminal): close recolor state gaps

* fix(terminal): retain saved colors across recolor

* fix(terminal): serialize recolor side effects

* fix(terminal): color keywords in place without history rebuild

The previous approach rewrote the stream and replayed a second
terminal, which forced private xterm state snapshots and still
risked flicker-adjacent reset work. Writes now stay pristine and
only dirty cells get a new foreground. Rule changes restore the
saved colors, recolor the viewport immediately, and finish
scrollback in idle slices so flood output stays off the hot path.

Related to #2784
Related to #2879

* fix(terminal): keep in-place keyword coloring correct under load

Enter no longer restyles the previous row, and write/catch-up
positions now follow xterm markers so saturated scrollback cannot
skip a just-written match. Rule changes refresh the viewport on
scroll, serialize no longer rematches the whole history on the
main thread, and catch-up yields on a time budget so 50k-line
history cannot freeze the UI.

Related to #2784
Related to #2879

* perf(terminal): keep flood and scroll off the highlight hot path

Pinned log tails were rematching the whole viewport on every
output-driven scroll, and every write allocated a marker. Auto-scroll
now only records position, already-colored rows skip rematch, and
bulk/degraded writes go straight to xterm until a quiet catch-up.

Related to #2784
Related to #2879

* perf(terminal): merge flood writes on a 16ms burst window

Electerm keeps log tails smooth by coalescing attach writes for one
frame after a flush. Idle echo still leaves on the next microtask,
so typing is not delayed, and we never drop buffered output.

Related to #2784
Related to #2879

* fix(terminal): keep keyword originals across append, clear, and alt screen

Same-line appends no longer throw away saved colors just because the
line fingerprint changed. Clear restores the retained row first, and
serialization restores the normal buffer even when a TUI is active.
Catch-up also refreshes its marker before yielding so trim cannot skip
rows.

Related to #2784
Related to #2879

* fix(ci): stop resetting highlight catch-up on every flood write

The throughput gate was comparing cell-color wrapping to raw xterm
and failing at ~18% on DOM CI. Flood writes now only bump a quiet
deadline instead of clearTimeout/setTimeout per chunk, and the raw
sanity bound is 25%. The product check remains 10% versus main.

Related to #2784
Related to #2879

* fix(terminal): rematch recycled rows and cap wrapped catch-up

Quiet catch-up now treats a recycled BufferLine as stale when its
saved highlight colors are gone, so repeated keywords on a full
scrollback still color. Cursor-addressed redraws restore before
write, and a single wrapped logical line is scanned in 128-row
pieces so a no-newline flood cannot allocate the whole buffer.

Related to #2784
Related to #2879

* fix(terminal): accept plugin #RRGGBBAA highlight colors

Plugin decorations allow 8-digit hex. Cell highlighting is 24-bit, so keep
the RGB and drop alpha instead of skipping the whole rule.

* fix(terminal): color cells for partial grapheme matches

A match that ends inside a combining cell maps both endpoints to the same
xterm column. Color that cell instead of building an empty range.

* fix(terminal): rematch flood rows after empty-line stamps

A hot-path \r\n write stamped the following empty cursor row as current.
The next flood chunk reused that BufferLine with ERROR text, and quiet
catch-up skipped it. Fingerprint the stamped content so filled or
recycled identical rows are recolored.

* perf(terminal): avoid flood-path registerMarker after trim

Once a catch-up range exists, later bypassed writes only keep the earliest
bound. A disposed marker collapses to 0 without allocating a new one on
every saturated-scrollback chunk.

* fix(terminal): recolor the row retained by clear

xterm clear keeps the cursor row after we restore originals. Recolor that
surviving line so enabled rules still apply until the next write.

* perf(terminal): stamp no-match rows without cell snapshots

Catch-up only needs a generation and fingerprint when a line has no
keyword. Allocate typed-array originals when a cell is actually colored.

* perf(terminal): treat pinned-bottom recycle as output scroll

Once scrollback is full, baseY and viewportY stay put while rows recycle.
That was treated as a user scroll, so every flood write rematched the
visible area. Keep pinned-to-bottom updates off the rematch path.

* perf(terminal): keep quiet catch-up to a single viewport paint

Catch-up already refreshes visible slices. A trailing recolorVisible()
caused a second settle paint and tripped the atomic-repaint gate.

---------

Co-authored-by: netcatty-bot <308658023+netcatty-bot@users.noreply.github.com>
2026-08-13 21:26:16 +08:00

499 lines
16 KiB
TypeScript

import test from 'node:test';
import assert from 'node:assert/strict';
import { CursorLineHighlighter } from './cursorLineHighlight.ts';
type Handler = () => void;
type FakeElement = {
style: Record<string, string>;
attributes: Record<string, string>;
setAttribute: (name: string, value: string) => void;
};
const createFakeTerm = (cols = 80) => {
let cursorY = 0;
let cursorX = 0;
let hasSelection = false;
let baseY = 0;
let bufferType: 'normal' | 'alternate' = 'normal';
let lineLength = cols;
const coloredBackgrounds = new Set<number>();
const coloredForegrounds = new Set<number>();
const inverseCells = new Set<number>();
const cursorMoveHandlers: Handler[] = [];
const writeParsedHandlers: Handler[] = [];
const resizeHandlers: Handler[] = [];
const bufferChangeHandlers: Handler[] = [];
const renderHandlers: Handler[] = [];
const selectionChangeHandlers: Handler[] = [];
const decorations: Array<{
options: Record<string, unknown>;
disposed: boolean;
element: FakeElement;
dispose: () => void;
onRender: (handler: (element: FakeElement) => void) => { dispose: () => void };
onDispose: (handler: Handler) => { dispose: () => void };
}> = [];
const markers: Array<{ line: number; disposed: boolean }> = [];
const term = {
cols,
buffer: {
active: {
get type() {
return bufferType;
},
get baseY() {
return baseY;
},
get cursorY() {
return cursorY;
},
get cursorX() {
return cursorX;
},
getLine() {
return {
length: cols,
getCell(x: number) {
return {
getChars: () => (x < lineLength ? 'x' : ''),
getWidth: () => 1,
isAttributeDefault: () => x >= lineLength,
isBgDefault: () => !coloredBackgrounds.has(x),
isFgDefault: () => !coloredForegrounds.has(x),
isInverse: () => (inverseCells.has(x) ? 1 : 0),
};
},
};
},
getNullCell() {
return { isBgDefault: () => true };
},
},
onBufferChange(handler: Handler) {
bufferChangeHandlers.push(handler);
return { dispose() {} };
},
},
onCursorMove(handler: Handler) {
cursorMoveHandlers.push(handler);
return { dispose() {} };
},
onResize(handler: Handler) {
resizeHandlers.push(handler);
return { dispose() {} };
},
onWriteParsed(handler: Handler) {
writeParsedHandlers.push(handler);
return { dispose() {} };
},
onRender(handler: Handler) {
renderHandlers.push(handler);
return { dispose() {} };
},
onSelectionChange(handler: Handler) {
selectionChangeHandlers.push(handler);
return { dispose() {} };
},
hasSelection() {
return hasSelection;
},
registerMarker(offset: number) {
const marker = {
line: baseY + cursorY + offset,
disposed: false,
get isDisposed() {
return this.disposed;
},
dispose() {
this.disposed = true;
},
};
markers.push(marker);
return marker;
},
registerDecoration(options: Record<string, unknown>) {
const disposeHandlers = new Set<Handler>();
const element: FakeElement = {
style: {},
attributes: {},
setAttribute(name, value) {
this.attributes[name] = value;
},
};
const decoration = {
options,
disposed: false,
element,
dispose() {
if (this.disposed) return;
this.disposed = true;
for (const handler of disposeHandlers) handler();
disposeHandlers.clear();
},
onDispose(handler: Handler) {
disposeHandlers.add(handler);
return { dispose: () => disposeHandlers.delete(handler) };
},
onRender(handler: (element: FakeElement) => void) {
handler(element);
return { dispose() {} };
},
};
decorations.push(decoration);
return decoration;
},
moveCursor(nextY: number) {
cursorY = nextY;
for (const handler of cursorMoveHandlers) handler();
for (const handler of renderHandlers) handler();
},
scrollOutput(lines: number) {
baseY += lines;
for (const handler of writeParsedHandlers) handler();
for (const handler of renderHandlers) handler();
},
writeHiddenOutput(lines: number) {
baseY += lines;
for (const handler of writeParsedHandlers) handler();
},
trimScrollback(lines: number) {
for (const marker of markers) {
if (!marker.disposed) marker.line -= lines;
}
for (const handler of writeParsedHandlers) handler();
for (const handler of renderHandlers) handler();
},
setBufferType(nextType: 'normal' | 'alternate') {
bufferType = nextType;
for (const handler of bufferChangeHandlers) handler();
},
setColoredBackgrounds(columns: number[]) {
coloredBackgrounds.clear();
for (const column of columns) coloredBackgrounds.add(column);
for (const handler of writeParsedHandlers) handler();
for (const handler of renderHandlers) handler();
},
setLineLength(nextLength: number) {
lineLength = nextLength;
for (const handler of writeParsedHandlers) handler();
for (const handler of renderHandlers) handler();
},
setCursorX(nextX: number) {
cursorX = nextX;
for (const handler of cursorMoveHandlers) handler();
for (const handler of renderHandlers) handler();
},
setSelection(next: boolean) {
hasSelection = next;
for (const handler of selectionChangeHandlers) handler();
},
render() {
for (const handler of renderHandlers) handler();
},
setColoredForegrounds(columns: number[]) {
coloredForegrounds.clear();
for (const column of columns) coloredForegrounds.add(column);
for (const handler of writeParsedHandlers) handler();
for (const handler of renderHandlers) handler();
},
setInverseCells(columns: number[]) {
inverseCells.clear();
for (const column of columns) inverseCells.add(column);
for (const handler of writeParsedHandlers) handler();
for (const handler of renderHandlers) handler();
},
resetDecorations() {
for (const decoration of decorations) decoration.dispose();
},
setCols(nextCols: number) {
term.cols = nextCols;
for (const handler of resizeHandlers) handler();
},
decorations,
markers,
};
return term;
};
test('CursorLineHighlighter paints an opaque background without changing text', () => {
const term = createFakeTerm(100);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setBackgroundColor('#263449');
highlighter.setEnabled(true);
assert.equal(term.decorations.length, 1);
assert.equal(term.decorations[0]?.options.width, 100);
assert.equal(term.decorations[0]?.options.backgroundColor, '#263449');
assert.equal(term.decorations[0]?.options.layer, 'bottom');
highlighter.dispose();
});
test('CursorLineHighlighter gives selection and search matches priority', () => {
const term = createFakeTerm(10);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
assert.equal(term.decorations.at(-1)?.disposed, false);
term.setSelection(true);
assert.equal(term.decorations.at(-1)?.disposed, true);
term.setSelection(false);
assert.equal(term.decorations.at(-1)?.disposed, false);
highlighter.dispose();
});
test('CursorLineHighlighter refreshes after hidden writes become visible', () => {
const term = createFakeTerm(10);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
assert.equal(term.markers.at(-1)?.line, 0);
term.writeHiddenOutput(1);
assert.equal(term.decorations.length, 1);
term.render();
assert.equal(term.decorations.length, 2);
assert.equal(term.decorations[0]?.disposed, true);
assert.equal(term.markers.at(-1)?.line, 1);
highlighter.dispose();
});
test('CursorLineHighlighter keeps a continuous background under colored keyword text', () => {
const term = createFakeTerm(10);
const keywordMarker = term.registerMarker(0);
term.registerDecoration({
marker: keywordMarker,
x: 2,
width: 2,
foregroundColor: '#F87171',
});
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setBackgroundColor('#263449');
highlighter.setEnabled(true);
assert.equal(term.decorations[0]?.options.foregroundColor, '#F87171');
assert.equal(term.decorations[0]?.options.backgroundColor, undefined);
assert.equal(term.decorations[1]?.options.x, 0);
assert.equal(term.decorations[1]?.options.width, 10);
assert.equal(term.decorations[1]?.options.backgroundColor, '#263449');
assert.equal(term.decorations[1]?.options.layer, 'bottom');
highlighter.dispose();
});
test('CursorLineHighlighter leaves ANSI background cells untouched', () => {
const term = createFakeTerm(10);
term.setColoredBackgrounds([2, 3, 7]);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setBackgroundColor('#263449');
highlighter.setEnabled(true);
assert.deepEqual(
term.decorations.map(({ options }) => ({ x: options.x, width: options.width })),
[
{ x: 0, width: 2 },
{ x: 4, width: 3 },
{ x: 8, width: 2 },
],
);
highlighter.dispose();
});
test('CursorLineHighlighter fills the blank tail after short output', () => {
const term = createFakeTerm(10);
term.setLineLength(4);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setBackgroundColor('#263449');
highlighter.setEnabled(true);
assert.equal(term.decorations.length, 2);
assert.equal(term.decorations[0]?.options.width, 4);
assert.equal(term.decorations[1]?.options.x, 4);
assert.equal(term.decorations[1]?.options.width, 6);
assert.equal(term.decorations[1]?.options.backgroundColor, '#263449');
assert.equal(term.decorations[1]?.options.layer, 'bottom');
highlighter.dispose();
});
test('CursorLineHighlighter fills the blank tail through the cursor cell', () => {
const term = createFakeTerm(10);
term.setLineLength(4);
term.setCursorX(5);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setBackgroundColor('#263449');
highlighter.setEnabled(true);
assert.deepEqual(
term.decorations.map(({ options }) => ({ x: options.x, width: options.width })),
[
{ x: 0, width: 4 },
{ x: 4, width: 6 },
],
);
highlighter.dispose();
});
test('CursorLineHighlighter fills a wrap-pending final cell', () => {
const term = createFakeTerm(10);
term.setLineLength(4);
term.setCursorX(10);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setBackgroundColor('#263449');
highlighter.setEnabled(true);
assert.deepEqual(
term.decorations.map(({ options }) => ({ x: options.x, width: options.width })),
[
{ x: 0, width: 4 },
{ x: 4, width: 6 },
],
);
highlighter.dispose();
});
test('CursorLineHighlighter keeps foreground colors and leaves inverse cells untouched', () => {
const term = createFakeTerm(10);
term.setColoredForegrounds([2, 3]);
term.setInverseCells([7]);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setBackgroundColor('#263449');
highlighter.setEnabled(true);
assert.deepEqual(
term.decorations.map(({ options }) => ({ x: options.x, width: options.width })),
[
{ x: 0, width: 7 },
{ x: 8, width: 2 },
],
);
highlighter.dispose();
});
test('CursorLineHighlighter follows cursor moves and clears when disabled', () => {
const term = createFakeTerm(80);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
assert.equal(term.decorations.length, 1);
term.moveCursor(3);
assert.equal(term.decorations.length, 2);
assert.equal(term.decorations[0]?.disposed, true);
assert.equal(term.decorations[1]?.disposed, false);
highlighter.setEnabled(false);
assert.equal(term.decorations[1]?.disposed, true);
highlighter.dispose();
});
test('CursorLineHighlighter swaps decorations atomically on refresh', () => {
const term = createFakeTerm(80);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
const firstDecoration = term.decorations[0];
assert.ok(firstDecoration);
assert.equal(firstDecoration.disposed, false);
let sawOverlap = false;
const originalRegisterMarker = term.registerMarker.bind(term);
term.registerMarker = (offset: number) => {
// New marker must be created while the previous decoration is still live.
if (!firstDecoration.disposed) sawOverlap = true;
return originalRegisterMarker(offset);
};
term.moveCursor(2);
assert.equal(sawOverlap, true, 'new marker should register before old decoration disposal');
assert.equal(firstDecoration.disposed, true);
assert.equal(term.decorations.at(-1)?.disposed, false);
highlighter.dispose();
});
test('CursorLineHighlighter recreates on resize and overlay color changes', () => {
const term = createFakeTerm(40);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
highlighter.setBackgroundColor('#112233');
assert.equal(
term.decorations.at(-1)?.options.backgroundColor,
'#112233',
);
assert.equal(term.decorations.at(-1)?.options.width, 40);
term.setCols(120);
assert.equal(term.decorations.at(-2)?.options.width, 40);
assert.equal(term.decorations.at(-1)?.options.width, 80);
highlighter.setBackgroundColor('#445566');
assert.equal(
term.decorations.at(-2)?.options.backgroundColor,
'#445566',
);
highlighter.dispose();
});
test('CursorLineHighlighter follows bottom-row output when only baseY changes', () => {
const term = createFakeTerm(80);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
assert.equal(term.markers.at(-1)?.line, 0);
term.scrollOutput(3);
assert.equal(term.decorations.length, 2);
assert.equal(term.decorations[0]?.disposed, true);
assert.equal(term.markers.at(-1)?.line, 3);
assert.equal(term.decorations.at(-1)?.disposed, false);
highlighter.dispose();
});
test('CursorLineHighlighter refreshes when saturated scrollback moves its marker', () => {
const term = createFakeTerm(80);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
const originalMarker = term.markers.at(-1);
assert.equal(originalMarker?.line, 0);
term.trimScrollback(1);
assert.equal(originalMarker?.disposed, true);
assert.equal(term.decorations.length, 2);
assert.equal(term.markers.at(-1)?.line, 0);
assert.equal(term.decorations.at(-1)?.disposed, false);
highlighter.dispose();
});
test('CursorLineHighlighter restores after the terminal resets its decorations', () => {
const term = createFakeTerm(80);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
assert.equal(term.decorations.length, 1);
term.resetDecorations();
assert.equal(term.decorations[0]?.disposed, true);
term.scrollOutput(0);
assert.equal(term.decorations.length, 2);
assert.equal(term.decorations.at(-1)?.disposed, false);
highlighter.dispose();
});
test('CursorLineHighlighter clears in the alternate buffer and restores in normal buffer', () => {
const term = createFakeTerm(80);
const highlighter = new CursorLineHighlighter(term as never);
highlighter.setEnabled(true);
assert.equal(term.decorations.at(-1)?.disposed, false);
term.setBufferType('alternate');
assert.equal(term.decorations.at(-1)?.disposed, true);
const decorationCount = term.decorations.length;
term.moveCursor(4);
term.scrollOutput(1);
assert.equal(term.decorations.length, decorationCount);
term.setBufferType('normal');
assert.equal(term.decorations.length, decorationCount + 1);
assert.equal(term.decorations.at(-1)?.disposed, false);
highlighter.dispose();
});