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

382 lines
11 KiB
TypeScript

import assert from "node:assert/strict";
import { beforeEach, test } from "node:test";
import {
createWriteCoalescer,
MAX_PENDING_WRITE_COALESCE_BYTES,
WRITE_COALESCE_BURST_MS,
type WriteCoalescerOptions,
} from "./writeCoalescer.ts";
type FrameCallback = (time: number) => void;
let frameCallbacks: Map<number, FrameCallback>;
let timeoutCallbacks: Map<number, () => void>;
let nextFrameId: number;
const createTestCoalescer = (
write: (data: string) => void,
options: Omit<WriteCoalescerOptions, "scheduleFrame" | "scheduleTimeout"> = {},
) =>
createWriteCoalescer(write, {
...options,
scheduleFrame(callback) {
const id = nextFrameId;
nextFrameId += 1;
frameCallbacks.set(id, callback);
return () => {
frameCallbacks.delete(id);
};
},
scheduleTimeout(callback) {
const id = nextFrameId;
nextFrameId += 1;
timeoutCallbacks.set(id, callback);
return () => {
timeoutCallbacks.delete(id);
};
},
});
const fireFrame = (): void => {
const callbacks = [...frameCallbacks.values()];
frameCallbacks.clear();
for (const callback of callbacks) {
callback(performance.now());
}
};
const fireTimeout = (): void => {
const callbacks = [...timeoutCallbacks.values()];
timeoutCallbacks.clear();
for (const callback of callbacks) {
callback();
}
};
beforeEach(() => {
frameCallbacks = new Map();
timeoutCallbacks = new Map();
nextFrameId = 1;
});
test("coalesces chunks in the same frame into one write", () => {
const writes: string[] = [];
const coalescer = createTestCoalescer((data) => writes.push(data));
coalescer.push("foo");
coalescer.push("bar");
coalescer.push("baz");
assert.equal(writes.length, 0);
fireFrame();
assert.deepEqual(writes, ["foobarbaz"]);
});
test("microtask schedule mode flushes after the current turn without rAF", async () => {
const writes: string[] = [];
const coalescer = createWriteCoalescer((data) => writes.push(data), {
resolveScheduleMode: () => "microtask",
});
coalescer.push("a");
coalescer.push("b");
assert.equal(writes.length, 0);
await Promise.resolve();
assert.deepEqual(writes, ["ab"]);
coalescer.dispose();
});
test("burst mode flushes idle output on the next microtask", async () => {
const writes: string[] = [];
const coalescer = createWriteCoalescer((data) => writes.push(data), {
resolveScheduleMode: () => "burst",
});
coalescer.push("a");
coalescer.push("b");
assert.equal(writes.length, 0);
await Promise.resolve();
assert.deepEqual(writes, ["ab"]);
coalescer.dispose();
});
test("burst mode merges writes that arrive inside the 16ms window", () => {
const writes: string[] = [];
let now = 1000;
const timeouts: Array<{ callback: () => void; ms: number }> = [];
const coalescer = createWriteCoalescer((data) => writes.push(data), {
resolveScheduleMode: () => "burst",
now: () => now,
burstWindowMs: WRITE_COALESCE_BURST_MS,
scheduleTimeout(callback, ms) {
timeouts.push({ callback, ms: ms ?? 0 });
return () => {
const index = timeouts.findIndex((entry) => entry.callback === callback);
if (index >= 0) timeouts.splice(index, 1);
};
},
});
coalescer.push("first");
coalescer.flushSync();
assert.deepEqual(writes, ["first"]);
now += 4;
coalescer.push("second");
coalescer.push("third");
assert.deepEqual(writes, ["first"]);
assert.equal(timeouts.length, 1);
assert.ok(timeouts[0]!.ms <= WRITE_COALESCE_BURST_MS);
timeouts[0]!.callback();
assert.deepEqual(writes, ["first", "secondthird"]);
coalescer.dispose();
});
test("upgrades a pending microtask schedule to rAF when a later chunk requests it", () => {
const writes: string[] = [];
const microtasks: Array<() => void> = [];
const frames: Array<() => void> = [];
let modeForChunk = "microtask" as "microtask" | "raf";
const originalMicrotask = globalThis.queueMicrotask;
const originalRaf = Object.getOwnPropertyDescriptor(globalThis, "requestAnimationFrame");
const originalCancel = Object.getOwnPropertyDescriptor(globalThis, "cancelAnimationFrame");
globalThis.queueMicrotask = (callback: () => void) => {
microtasks.push(callback);
};
Object.defineProperty(globalThis, "requestAnimationFrame", {
configurable: true,
value: (callback: FrameRequestCallback) => {
frames.push(() => callback(0));
return frames.length;
},
});
Object.defineProperty(globalThis, "cancelAnimationFrame", {
configurable: true,
value: () => {},
});
try {
const coalescer = createWriteCoalescer((data) => writes.push(data), {
resolveScheduleMode: () => modeForChunk,
});
coalescer.push("shell");
assert.equal(microtasks.length, 1);
assert.equal(frames.length, 0);
modeForChunk = "raf";
coalescer.push("\x1b[?1049hTUI");
// Microtask cancelled; rAF armed for the combined batch.
assert.equal(frames.length, 1);
assert.deepEqual(writes, []);
// Cancelled microtask must not flush.
for (const task of microtasks.splice(0)) task();
assert.deepEqual(writes, []);
frames[0]!();
assert.deepEqual(writes, ["shell\x1b[?1049hTUI"]);
coalescer.dispose();
} finally {
globalThis.queueMicrotask = originalMicrotask;
if (originalRaf) {
Object.defineProperty(globalThis, "requestAnimationFrame", originalRaf);
} else {
Reflect.deleteProperty(globalThis, "requestAnimationFrame");
}
if (originalCancel) {
Object.defineProperty(globalThis, "cancelAnimationFrame", originalCancel);
} else {
Reflect.deleteProperty(globalThis, "cancelAnimationFrame");
}
}
});
test("coalesces a large TUI repaint until the scheduled frame", () => {
const writes: string[] = [];
const coalescer = createTestCoalescer((data) => writes.push(data));
const chunk = "x".repeat(4 * 1024);
for (let index = 0; index < 20; index += 1) {
coalescer.push(chunk);
}
assert.equal(writes.length, 0);
fireFrame();
assert.deepEqual(writes.map((write) => write.length), [80 * 1024]);
});
test("schedules a new frame for data arriving after a flush", () => {
const writes: string[] = [];
const coalescer = createTestCoalescer((data) => writes.push(data));
coalescer.push("first");
fireFrame();
coalescer.push("second");
fireFrame();
assert.deepEqual(writes, ["first", "second"]);
});
test("flushSync writes pending bytes immediately and cancels the scheduled frame", () => {
const writes: string[] = [];
const coalescer = createTestCoalescer((data) => writes.push(data));
coalescer.push("pending");
coalescer.flushSync();
assert.deepEqual(writes, ["pending"]);
fireFrame();
assert.deepEqual(writes, ["pending"]);
});
test("flushes synchronously when pending bytes exceed the cap", () => {
const writes: string[] = [];
const coalescer = createTestCoalescer((data) => writes.push(data));
const chunk = "x".repeat(MAX_PENDING_WRITE_COALESCE_BYTES);
coalescer.push(chunk);
coalescer.push("y");
assert.equal(writes.length, 1);
assert.equal(writes[0]?.length, MAX_PENDING_WRITE_COALESCE_BYTES + 1);
});
test("uses a tighter pending-byte cap when getMaxPendingBytes is set", () => {
const writes: string[] = [];
const cap = 64;
const coalescer = createTestCoalescer((data) => writes.push(data), {
getMaxPendingBytes: () => cap,
});
coalescer.push("x".repeat(cap - 1));
coalescer.push("yy");
assert.equal(writes.length, 1);
assert.equal(writes[0]?.length, cap + 1);
});
test("byte-cap flushes even while scheduled frames are gated", () => {
const writes: string[] = [];
let canFlush = false;
const cap = 8;
const coalescer = createTestCoalescer((data) => writes.push(data), {
getMaxPendingBytes: () => cap,
shouldFlushScheduledFrame: () => canFlush,
});
// Under the cap: gated frame holds.
coalescer.push("x".repeat(cap));
fireFrame();
assert.deepEqual(writes, []);
// Past the cap: drain immediately so hidden log floods stay bounded.
coalescer.push("y");
assert.deepEqual(writes, ["x".repeat(cap) + "y"]);
});
test("still resolves schedule mode before gated under-cap frames and cap drains", () => {
const writes: string[] = [];
let canFlush = false;
const probed: string[] = [];
const cap = 8;
const coalescer = createTestCoalescer((data) => writes.push(data), {
getMaxPendingBytes: () => cap,
shouldFlushScheduledFrame: () => canFlush,
resolveScheduleMode: ({ nextChunk }) => {
probed.push(nextChunk);
return nextChunk.includes("\x1b[?1049h") ? "raf" : "microtask";
},
});
// First chunk arms a gated under-cap frame; second exceeds cap and drains.
// resolveScheduleMode must still run so enter-alt latches fire.
coalescer.push("shell");
coalescer.push(`\x1b[?1049h${"x".repeat(cap)}`);
assert.deepEqual(probed, ["shell", `\x1b[?1049h${"x".repeat(cap)}`]);
assert.equal(writes.join("").includes("\x1b[?1049h"), true);
assert.equal(writes.join("").startsWith("shell"), true);
});
test("dispose flushes remaining bytes and stops accepting new chunks", () => {
const writes: string[] = [];
const coalescer = createTestCoalescer((data) => writes.push(data));
coalescer.push("tail");
coalescer.dispose();
assert.deepEqual(writes, ["tail"]);
coalescer.push("ignored");
fireFrame();
assert.deepEqual(writes, ["tail"]);
});
test("raf output drains when the animation frame callback never arrives", () => {
const writes: string[] = [];
const coalescer = createWriteCoalescer((data) => writes.push(data), {
scheduleFrame() {
// Chromium can suppress an already-requested frame while a window is
// occluded. Keep the callback pending forever to reproduce that edge.
return () => {};
},
scheduleTimeout(callback) {
timeoutCallbacks.set(1, callback);
return () => timeoutCallbacks.delete(1);
},
});
coalescer.push("stranded");
assert.deepEqual(writes, []);
fireTimeout();
assert.deepEqual(writes, ["stranded"]);
coalescer.dispose();
});
test("a gated frame keeps retrying until the terminal becomes visible", () => {
const writes: string[] = [];
let canFlush = false;
const coalescer = createTestCoalescer((data) => writes.push(data), {
shouldFlushScheduledFrame: () => canFlush,
});
coalescer.push("held");
fireFrame();
assert.deepEqual(writes, []);
assert.equal(coalescer.pendingBytes(), 4);
canFlush = true;
fireTimeout();
assert.deepEqual(writes, ["held"]);
assert.equal(coalescer.pendingBytes(), 0);
coalescer.dispose();
});
test("continuous sub-deadline chunks cannot postpone the wall-clock drain", () => {
const writes: string[] = [];
const coalescer = createWriteCoalescer((data) => writes.push(data), {
scheduleFrame() {
return () => {};
},
scheduleTimeout(callback) {
timeoutCallbacks.set(1, callback);
return () => timeoutCallbacks.delete(1);
},
});
try {
coalescer.push("a");
for (let index = 0; index < 8; index += 1) {
coalescer.push("x");
}
assert.equal(timeoutCallbacks.size, 1);
fireTimeout();
assert.ok(writes.length > 0, "continuous ingress must drain before it becomes idle");
} finally {
coalescer.dispose();
}
});