Files
Netcatty/components/terminal/runtime/terminalOutputPressure.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

277 lines
9.9 KiB
TypeScript

import assert from "node:assert/strict";
import test from "node:test";
import type { Terminal as XTerm } from "@xterm/xterm";
import {
getTerminalOutputPressure,
isTerminalScrollbackSaturated,
noteTerminalOutputPressureData,
resetTerminalOutputPressure,
setTerminalOutputPressureVisibility,
shouldDegradeTerminalSideWork,
shouldDegradeTerminalKeywordHighlight,
shouldSkipTerminalLineTimestamps,
} from "./terminalOutputPressure.ts";
import { TERMINAL_LONG_LINE_PRESSURE_BYTES } from "./terminalFlowConstants.ts";
import { XTERM_PERFORMANCE_CONFIG } from "../../../infrastructure/config/xtermPerformance.ts";
const createFakeTerm = (overrides: Record<string, unknown> = {}) => ({
rows: 24,
options: { scrollback: 1000 },
buffer: { active: { length: 10, baseY: 0 } },
...overrides,
}) as unknown as XTerm;
test("tracks long unbroken terminal output pressure until a line break arrives", () => {
const term = createFakeTerm();
noteTerminalOutputPressureData(term, "x".repeat(TERMINAL_LONG_LINE_PRESSURE_BYTES - 1));
assert.equal(getTerminalOutputPressure(term).longLine, false);
noteTerminalOutputPressureData(term, "x");
assert.equal(getTerminalOutputPressure(term).longLine, true);
assert.equal(getTerminalOutputPressure(term).mode, "long-line");
noteTerminalOutputPressureData(term, "\nshort");
assert.equal(getTerminalOutputPressure(term).longLine, false);
// Crossing the long-line threshold also arms the high-rate large-output window.
assert.equal(getTerminalOutputPressure(term).largeOutput, true);
assert.equal(getTerminalOutputPressure(term).mode, "large-output");
resetTerminalOutputPressure(term);
});
test("reports newline-terminated long terminal lines as long-line pressure", () => {
const term = createFakeTerm();
noteTerminalOutputPressureData(term, `${"x".repeat(TERMINAL_LONG_LINE_PRESSURE_BYTES)}\n`);
assert.equal(getTerminalOutputPressure(term).longLine, true);
assert.equal(getTerminalOutputPressure(term).mode, "long-line");
assert.equal(getTerminalOutputPressure(term).consecutiveUnbrokenBytes, 0);
noteTerminalOutputPressureData(term, "short\n");
assert.equal(getTerminalOutputPressure(term).longLine, false);
assert.equal(getTerminalOutputPressure(term).largeOutput, true);
assert.equal(getTerminalOutputPressure(term).mode, "large-output");
resetTerminalOutputPressure(term);
});
test("reports background pressure separately from output volume", () => {
const term = createFakeTerm();
setTerminalOutputPressureVisibility(term, false);
assert.equal(getTerminalOutputPressure(term).background, true);
assert.equal(getTerminalOutputPressure(term).mode, "background");
assert.equal(shouldDegradeTerminalSideWork(term), false);
setTerminalOutputPressureVisibility(term, true);
assert.equal(getTerminalOutputPressure(term).background, false);
assert.equal(getTerminalOutputPressure(term).mode, "normal");
resetTerminalOutputPressure(term);
});
test("keeps large-output pressure through small input echoes until output is quiet", () => {
const term = createFakeTerm();
const originalNow = performance.now.bind(performance);
let now = 1_000;
Object.defineProperty(performance, "now", {
configurable: true,
value: () => now,
});
try {
noteTerminalOutputPressureData(term, "x\n".repeat(Math.ceil(TERMINAL_LONG_LINE_PRESSURE_BYTES / 2)));
assert.equal(getTerminalOutputPressure(term).largeOutput, true);
assert.equal(getTerminalOutputPressure(term).mode, "large-output");
now += 16;
noteTerminalOutputPressureData(term, "a");
assert.equal(getTerminalOutputPressure(term).largeOutput, true);
assert.equal(getTerminalOutputPressure(term).mode, "large-output");
now += XTERM_PERFORMANCE_CONFIG.highlighting.largeOutputQuietMs + 1;
assert.equal(getTerminalOutputPressure(term).largeOutput, false);
assert.equal(getTerminalOutputPressure(term).mode, "normal");
} finally {
Object.defineProperty(performance, "now", {
configurable: true,
value: originalNow,
});
resetTerminalOutputPressure(term);
}
});
test("detects large-output pressure from high-rate small chunks", () => {
const term = createFakeTerm();
const originalNow = performance.now.bind(performance);
let now = 5_000;
Object.defineProperty(performance, "now", {
configurable: true,
value: () => now,
});
try {
// ~16KB of short lines inside the 100ms rate window (not one unbroken run).
// Threshold is intentionally below one Tabby-sized xterm shard.
for (let index = 0; index < 16; index += 1) {
noteTerminalOutputPressureData(term, `${"y".repeat(1023)}\n`);
}
assert.equal(getTerminalOutputPressure(term).largeOutput, true);
assert.equal(getTerminalOutputPressure(term).longLine, false);
assert.equal(getTerminalOutputPressure(term).mode, "large-output");
} finally {
Object.defineProperty(performance, "now", {
configurable: true,
value: originalNow,
});
resetTerminalOutputPressure(term);
}
});
test("arms large-output early on multi-line writes when scrollback is saturated", () => {
// rows(24) + scrollback(1000) = 1024 max; length near cap → second-seq path.
const term = createFakeTerm({
rows: 24,
options: { scrollback: 1000 },
buffer: { active: { length: 1020, baseY: 996 } },
});
const originalNow = performance.now.bind(performance);
let now = 9_000;
Object.defineProperty(performance, "now", {
configurable: true,
value: () => now,
});
try {
assert.equal(isTerminalScrollbackSaturated(term), true);
// Far below the long-line / 16KB rate thresholds — only saturated multi-line
// arming should trip bulk mode (second `seq` cold start).
noteTerminalOutputPressureData(term, "1\n2\n3\n4\n5\n");
assert.equal(getTerminalOutputPressure(term).scrollbackSaturated, true);
assert.equal(getTerminalOutputPressure(term).largeOutput, true);
assert.equal(shouldDegradeTerminalSideWork(term), true);
assert.equal(getTerminalOutputPressure(term).mode, "large-output");
// Quiet window is extended while saturated so prompt-echo gaps do not
// reopen the expensive timestamp/highlight path before a second dump.
now += XTERM_PERFORMANCE_CONFIG.highlighting.largeOutputQuietMs + 1;
assert.equal(getTerminalOutputPressure(term).largeOutput, true);
now += XTERM_PERFORMANCE_CONFIG.highlighting.largeOutputQuietMs + 1;
assert.equal(getTerminalOutputPressure(term).largeOutput, false);
} finally {
Object.defineProperty(performance, "now", {
configurable: true,
value: originalNow,
});
resetTerminalOutputPressure(term);
}
});
test("a one-line prompt does not degrade keyword coloring on saturated scrollback", () => {
const term = createFakeTerm({
rows: 24,
options: { scrollback: 1000 },
buffer: { active: { length: 1020, baseY: 996 } },
});
const prompt = "\r\nplain prompt # ";
noteTerminalOutputPressureData(term, prompt);
assert.equal(shouldDegradeTerminalSideWork(term), true);
assert.equal(shouldDegradeTerminalKeywordHighlight(term, prompt), false);
resetTerminalOutputPressure(term);
});
test("does not treat an empty buffer as scrollback-saturated", () => {
const term = createFakeTerm({
rows: 24,
options: { scrollback: 1000 },
buffer: { active: { length: 12, baseY: 0 } },
});
assert.equal(isTerminalScrollbackSaturated(term), false);
noteTerminalOutputPressureData(term, "1\n2\n3\n");
assert.equal(getTerminalOutputPressure(term).largeOutput, false);
assert.equal(getTerminalOutputPressure(term).scrollbackSaturated, false);
resetTerminalOutputPressure(term);
});
test("saturated multi-line degrades side work but keeps line timestamps", () => {
const term = createFakeTerm({
rows: 24,
options: { scrollback: 1000 },
buffer: { active: { length: 1020, baseY: 996 } },
});
// docker-ps-sized multi-line on a full scrollback: highlight/prep may degrade,
// but per-line gutter timestamps must still stamp.
noteTerminalOutputPressureData(term, "CONTAINER ID IMAGE\n".repeat(20));
assert.equal(shouldDegradeTerminalSideWork(term), true);
assert.equal(
shouldDegradeTerminalKeywordHighlight(term, "CONTAINER ID IMAGE\n".repeat(20)),
false,
);
assert.equal(shouldSkipTerminalLineTimestamps(term), false);
resetTerminalOutputPressure(term);
});
test("true flood rate skips line timestamps", () => {
const term = createFakeTerm();
const originalNow = performance.now.bind(performance);
let now = 20_000;
Object.defineProperty(performance, "now", {
configurable: true,
value: () => now,
});
try {
// 64KB+ inside the rate window → timestamp flood gate.
for (let index = 0; index < 64; index += 1) {
noteTerminalOutputPressureData(term, `${"z".repeat(1023)}\n`);
}
assert.equal(shouldSkipTerminalLineTimestamps(term), true);
assert.equal(shouldDegradeTerminalSideWork(term), true);
} finally {
Object.defineProperty(performance, "now", {
configurable: true,
value: originalNow,
});
resetTerminalOutputPressure(term);
}
});
test("rate detector uses a true rolling window across early tiny samples", () => {
const term = createFakeTerm();
const originalNow = performance.now.bind(performance);
let now = 1;
Object.defineProperty(performance, "now", {
configurable: true,
value: () => now,
});
try {
noteTerminalOutputPressureData(term, "x\n");
now = 60;
noteTerminalOutputPressureData(term, `${"x".repeat(40 * 1024)}\n`);
now = 102;
noteTerminalOutputPressureData(term, `${"x".repeat(40 * 1024)}\n`);
// 80KB arrived within 42ms; the tiny sample at t=1 should age out, not reset the window.
assert.equal(getTerminalOutputPressure(term).largeOutput, true);
assert.equal(getTerminalOutputPressure(term).mode, "large-output");
} finally {
Object.defineProperty(performance, "now", {
configurable: true,
value: originalNow,
});
resetTerminalOutputPressure(term);
}
});