From e8e696971f39ee136badfe4cb5484c7f17af28bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E5=A4=A7=E7=8C=AB?= <16399091+binaricat@users.noreply.github.com> Date: Thu, 13 Aug 2026 21:26:16 +0800 Subject: [PATCH] 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> --- .github/workflows/test.yml | 13 +- components/Terminal.tsx | 10 +- components/terminal/keywordHighlight.test.ts | 3333 +++-------------- components/terminal/keywordHighlight.ts | 2736 ++++---------- .../pluginTerminalVisualProviderHost.test.ts | 62 + .../pluginTerminalVisualProviderHost.ts | 45 +- .../runtime/createTerminalSessionStarters.ts | 3 +- .../createTerminalSessionStarters.types.ts | 1 + .../terminal/runtime/createXTermRuntime.ts | 6 +- .../runtime/cursorLineHighlight.test.ts | 7 +- .../terminal/runtime/cursorLineHighlight.ts | 8 +- .../terminal/runtime/terminalCloseCapture.ts | 2 +- .../runtime/terminalLineTimestamps.ts | 34 + .../runtime/terminalOutputPressure.test.ts | 20 + .../runtime/terminalOutputPressure.ts | 13 + .../runtime/terminalSessionAttachment.test.ts | 3 +- .../runtime/terminalSessionAttachment.ts | 3 +- .../runtime/terminalWriteCoalescer.test.ts | 6 +- .../runtime/terminalWriteCoalescer.ts | 14 +- .../terminal/runtime/writeCoalescer.test.ts | 48 + components/terminal/runtime/writeCoalescer.ts | 45 +- .../terminal/terminalHibernateRuntime.test.ts | 19 + .../terminal/terminalHibernateRuntime.ts | 3 +- components/terminal/useTerminalEffects.ts | 6 +- docs/plugin-platform/terminal-providers.md | 15 +- infrastructure/config/xtermPerformance.ts | 39 +- package.json | 3 +- scripts/github-workflow-ci.test.cjs | 2 +- ...xterm-decoration-performance.live.test.cjs | 206 - ...eyword-highlight-performance.live.test.cjs | 174 + ...keyword-highlight-throughput.live.test.cjs | 358 ++ 31 files changed, 2177 insertions(+), 5060 deletions(-) delete mode 100644 scripts/xterm-decoration-performance.live.test.cjs create mode 100644 scripts/xterm-keyword-highlight-performance.live.test.cjs create mode 100644 scripts/xterm-keyword-highlight-throughput.live.test.cjs diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index acbde1e74..0e69d9417 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -21,6 +21,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v7 + with: + fetch-depth: 0 - name: Setup Node uses: actions/setup-node@v7 @@ -50,11 +52,18 @@ jobs: - name: Test run: npm test - - name: Test terminal decoration performance + - name: Test terminal keyword highlight performance env: NETCATTY_TERMINAL_PERF_SHOW_WINDOW: "1" # GitHub-hosted runners do not configure Electron's SUID sandbox helper. - run: xvfb-run -a ./node_modules/.bin/electron --no-sandbox scripts/xterm-decoration-performance.live.test.cjs + run: xvfb-run -a ./node_modules/.bin/electron --no-sandbox scripts/xterm-keyword-highlight-performance.live.test.cjs + + - name: Test terminal keyword highlight throughput + env: + NETCATTY_TERMINAL_PERF_MAIN_REF: ${{ github.event.pull_request.base.sha || 'HEAD^' }} + NETCATTY_TERMINAL_PERF_ROUNDS: "3" + NETCATTY_TERMINAL_PERF_SHOW_WINDOW: "1" + run: xvfb-run -a ./node_modules/.bin/electron --no-sandbox scripts/xterm-keyword-highlight-throughput.live.test.cjs - name: Build run: npm run build diff --git a/components/Terminal.tsx b/components/Terminal.tsx index 514267bac..698ed2965 100644 --- a/components/Terminal.tsx +++ b/components/Terminal.tsx @@ -1513,6 +1513,7 @@ const TerminalComponent: React.FC = ({ return; } } + await xtermRuntimeRef.current?.keywordHighlighter.prepareForSerialization(); snapshot = serializeAddonRef.current.serialize() || ""; } else if (hibernatedRef.current || softHiddenRef.current) { // Hibernate path: live xterm is torn down; use retained snapshot. @@ -1696,6 +1697,7 @@ const TerminalComponent: React.FC = ({ } let serializedSnapshot: unknown; try { + await xtermRuntimeRef.current?.keywordHighlighter.prepareForSerialization(); serializedSnapshot = serializeAddonRef.current?.serialize?.(); } catch (err) { logger.warn("Failed to serialize terminal snapshot for attach popup", err); @@ -2053,7 +2055,11 @@ const TerminalComponent: React.FC = ({ const snapshot = await serializeTerminalForHibernate( term, serializeAddon, - { preferWasm: resolveHibernatePreferWasmSerialize(terminalSettingsRef.current) }, + { + preferWasm: resolveHibernatePreferWasmSerialize(terminalSettingsRef.current), + prepare: () => xtermRuntimeRef.current?.keywordHighlighter.prepareForSerialization() + ?? Promise.resolve(), + }, ); if (!canFinishHibernate()) return false; @@ -2175,6 +2181,8 @@ const TerminalComponent: React.FC = ({ termRef, fitAddonRef, serializeAddonRef, + prepareKeywordHighlightSerialization: () => xtermRuntimeRef.current + ?.keywordHighlighter.prepareForSerialization() ?? Promise.resolve(), searchAddonRef, hasRuntimeRef, }), []); diff --git a/components/terminal/keywordHighlight.test.ts b/components/terminal/keywordHighlight.test.ts index ed48dd875..b891796b8 100644 --- a/components/terminal/keywordHighlight.test.ts +++ b/components/terminal/keywordHighlight.test.ts @@ -1,2856 +1,547 @@ -import test from "node:test"; import assert from "node:assert/strict"; +import test from "node:test"; -import { - KeywordHighlighter, - MAX_PLUGIN_DECORATION_MATCHES_PER_LOGICAL_LINE, -} from "./keywordHighlight.ts"; -import type { KeywordHighlightRule } from "../../types.ts"; -import { - noteTerminalOutputPressureData, - resetTerminalOutputPressure, -} from "./runtime/terminalOutputPressure.ts"; -import { - TERMINAL_AUX_LONG_LINE_SCAN_LIMIT_CHARS, - TERMINAL_LONG_LINE_PRESSURE_BYTES, -} from "./runtime/terminalFlowConstants.ts"; -import { XTERM_PERFORMANCE_CONFIG } from "../../infrastructure/config/xtermPerformance.ts"; +import { createRequire } from "node:module"; +import type { SerializeAddon as SerializeAddonType } from "@xterm/addon-serialize"; +import type { Terminal as XTermType } from "@xterm/xterm"; -type RafCallback = (time: number) => void; +import { writeTerminalDataWithLineTimestamps } from "./runtime/terminalLineTimestamps.ts"; +import { noteTerminalOutputPressureData } from "./runtime/terminalOutputPressure.ts"; +import { KeywordHighlighter } from "./keywordHighlight.ts"; -function installAnimationFrameQueue() { - const callbacks = new Map(); - let nextId = 1; - const previousRequestAnimationFrame = globalThis.requestAnimationFrame; - const previousCancelAnimationFrame = globalThis.cancelAnimationFrame; +const require = createRequire(import.meta.url); +const { SerializeAddon } = require("@xterm/addon-serialize") as { + SerializeAddon: typeof SerializeAddonType; +}; +const { Terminal: XTerm } = require("@xterm/xterm") as { + Terminal: typeof XTermType; +}; - globalThis.requestAnimationFrame = ((callback: RafCallback) => { - const id = nextId; - nextId += 1; - callbacks.set(id, callback); - return id; - }) as typeof requestAnimationFrame; - globalThis.cancelAnimationFrame = ((id: number) => { - callbacks.delete(id); - }) as typeof cancelAnimationFrame; +const RED = 0xf87171; +const BLUE = 0x60a5fa; - const flushOne = () => { - const next = callbacks.entries().next().value as [number, RafCallback] | undefined; - if (!next) return; - callbacks.delete(next[0]); - next[1](performance.now()); - }; +const rule = (color = "#F87171") => [{ + id: "error", + label: "Error", + patterns: ["ERROR"], + color, + enabled: true, +}]; - return { - flushOne, - flush() { - while (callbacks.size > 0) { - flushOne(); - } - }, - restore() { - globalThis.requestAnimationFrame = previousRequestAnimationFrame; - globalThis.cancelAnimationFrame = previousCancelAnimationFrame; - }, - }; -} +const write = (term: XTermType, data: string): Promise => new Promise((resolve) => { + term.write(data, resolve); +}); -function createFakeLine(text: string, onTranslate?: () => void) { - return { - isWrapped: false, - length: text.length, - translateToString() { - onTranslate?.(); - return text; - }, - getCell(index: number) { - if (index < 0 || index >= text.length) return undefined; - return { - getChars: () => text[index], - getWidth: () => 1, - }; - }, - }; -} +const cellRgb = (term: XTermType, y: number, text: string): number | undefined => { + const line = term.buffer.active.getLine(y); + const raw = line?.translateToString(true) ?? ""; + const index = raw.indexOf(text); + if (index < 0) return undefined; + return line?.getCell(index)?.getFgColor(); +}; -let nextFakeMarkerId = 1; -let fakeMarkerLineReadCount = 0; +const uncoloredKeywordLines = (term: XTermType, text: string, rgb: number): number[] => { + const missed: number[] = []; + for (let y = 0; y < term.buffer.active.length; y += 1) { + const line = term.buffer.active.getLine(y); + const raw = line?.translateToString(true) ?? ""; + const index = raw.indexOf(text); + if (index < 0) continue; + if (line?.getCell(index)?.getFgColor() !== rgb) missed.push(y); + } + return missed; +}; -function createFakeMarker(line: number) { - const listeners = new Set<() => void>(); - let currentLine = line; - return { - id: nextFakeMarkerId++, - get line() { - fakeMarkerLineReadCount += 1; - return currentLine; - }, - set line(value: number) { - currentLine = value; - }, - isDisposed: false, - onDispose(listener: () => void) { - listeners.add(listener); - return { dispose: () => listeners.delete(listener) }; - }, - dispose() { - if (this.isDisposed) return; - this.isDisposed = true; - this.line = -1; - for (const listener of listeners) listener(); - listeners.clear(); - }, - }; -} +const firstRgbMatch = (term: XTermType, rgb: number): number => { + let count = 0; + for (let y = 0; y < term.buffer.active.length; y += 1) { + const line = term.buffer.active.getLine(y); + if (!line) continue; + for (let x = 0; x < line.length; x += 1) { + if (line.getCell(x)?.getFgColor() === rgb) count += 1; + } + } + return count; +}; -function createFakeWrappedLine(text: string, isWrapped: boolean) { - return { - ...createFakeLine(text), - isWrapped, - }; -} +test("new output is colored on the written cells without decorations", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "plain ERROR text"); -function createFakeTerminalFromLines(lines: Array<{ text: string; isWrapped: boolean }>) { - const fakeLines = lines.map((line) => createFakeWrappedLine(line.text, line.isWrapped)); - const decorations: Array<{ x: number; width: number; foregroundColor: string }> = []; - const noopDisposable = { dispose() {} }; - const term = { - rows: fakeLines.length, - cols: 80, - buffer: { - active: { - type: "normal", - viewportY: 0, - baseY: 0, - cursorY: 0, - length: fakeLines.length, - getLine: (lineY: number) => fakeLines[lineY], - }, - }, - onScroll: () => noopDisposable, - onData: () => noopDisposable, - onWriteParsed: () => noopDisposable, - onResize: () => noopDisposable, - onRender: () => noopDisposable, - registerMarker(offset: number) { - return createFakeMarker(offset); - }, - registerDecoration(options: { x: number; width: number; foregroundColor: string }) { - decorations.push(options); - return { - isDisposed: false, - dispose() { - this.isDisposed = true; - }, - }; - }, - refresh() {}, - }; - return { term, decorations }; -} + assert.equal(cellRgb(term, 0, "ERROR"), RED); + assert.equal(term.buffer.active.getLine(0)?.getCell(0)?.getFgColor(), -1); -function createFakeTerminalFromLargeWrappedBlock({ - lineCount, - lineText, - viewportY, - rows, -}: { - lineCount: number; - lineText: string; - viewportY: number; - rows: number; -}) { - let getLineCount = 0; - const decorations: Array<{ x: number; width: number; foregroundColor: string }> = []; - const noopDisposable = { dispose() {} }; - const handlers: { - scroll?: () => void; - data?: (data: string) => void; - writeParsed?: () => void; - resize?: () => void; - render?: () => void; - } = {}; - const term = { - rows, - cols: lineText.length, - buffer: { - active: { - type: "normal", - viewportY, - baseY: 0, - cursorY: viewportY, - length: lineCount, - getLine: (lineY: number) => { - getLineCount += 1; - if (lineY < 0 || lineY >= lineCount) return undefined; - return createFakeWrappedLine(lineText, lineY > 0); - }, - }, - }, - onScroll(handler: (viewportY: number) => void) { - handlers.scroll = () => handler(term.buffer.active.viewportY); - return noopDisposable; - }, - onData(handler: (data: string) => void) { - handlers.data = handler; - return noopDisposable; - }, - onWriteParsed(handler: () => void) { - handlers.writeParsed = handler; - return noopDisposable; - }, - onResize(handler: () => void) { - handlers.resize = handler; - return noopDisposable; - }, - onRender(handler: () => void) { - handlers.render = handler; - return noopDisposable; - }, - registerMarker(offset: number) { - return createFakeMarker(offset); - }, - registerDecoration(options: { x: number; width: number; foregroundColor: string }) { - decorations.push(options); - return { - isDisposed: false, - dispose() { - this.isDisposed = true; - }, - }; - }, - refresh() {}, - }; - return { - term, - decorations, - handlers, - getLineCount: () => getLineCount, - resetGetLineCount: () => { - getLineCount = 0; - }, - }; -} + highlighter.dispose(); + term.dispose(); +}); -function createFakeTerminal(lineText: string, options: { lineCount?: number } = {}) { - const lineCount = options.lineCount ?? 1; - let translateCount = 0; - const translatedLineIndexes: number[] = []; - const createLineAtIndex = (text: string, index: number) => - createFakeLine(text, () => { - translateCount += 1; - translatedLineIndexes.push(index); - }); - const lines = Array.from({ length: lineCount }, (_, index) => - createLineAtIndex(`${lineText} ${index}`, index) +test("ordinary Enter output does not revisit existing history", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "existing ERROR"); + await highlighter.whenSettled(); + const rebuildsBefore = highlighter.rebuildCount; + const before = cellRgb(term, 0, "ERROR"); + + await write(term, "\r\nplain prompt # "); + + assert.equal(cellRgb(term, 0, "ERROR"), before); + assert.equal(highlighter.rebuildCount, rebuildsBefore); + highlighter.dispose(); + term.dispose(); +}); + +test("changing or disabling rules recolors existing history from original cell colors", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const visibleSerializer = new SerializeAddon(); + term.loadAddon(visibleSerializer); + const highlighter = new KeywordHighlighter(term); + + highlighter.setRules(rule(), true); + await write(term, "first ERROR\r\nsecond ERROR"); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + assert.match(visibleSerializer.serialize(), /38;2;248;113;113m/); + assert.equal( + highlighter.serializeAddon.serialize(), + "first ERROR\r\nsecond ERROR", + "saved history must never contain Netcatty's injected colors", ); - const decorations: Array<{ x: number; width: number; foregroundColor: string }> = []; - const decorationStates: Array<{ - readonly line: number; - isDisposed: boolean; - dispose: () => void; - }> = []; - const markers: Array<{ - line: number; - isDisposed: boolean; - dispose: () => void; - }> = []; - const refreshCalls: Array<{ start: number; end: number }> = []; - const noopDisposable = { dispose() {} }; - const handlers: { - scroll?: () => void; - data?: (data: string) => void; - writeParsed?: () => void; - resize?: () => void; - render?: () => void; - } = {}; - const term = { - rows: 3, - cols: 80, - buffer: { - active: { - type: "normal", - viewportY: 0, - baseY: 0, - cursorY: 0, - length: lineCount, - getLine: (lineY: number) => lines[lineY], - }, - }, - onScroll: (handler: (viewportY: number) => void) => { - handlers.scroll = () => handler(term.buffer.active.viewportY); - return noopDisposable; - }, - onData: (handler: (data: string) => void) => { - handlers.data = handler; - return noopDisposable; - }, - onWriteParsed: (handler: () => void) => { - handlers.writeParsed = handler; - return noopDisposable; - }, - onResize: (handler: () => void) => { - handlers.resize = handler; - return noopDisposable; - }, - onRender: (handler: () => void) => { - handlers.render = handler; - return noopDisposable; - }, - registerMarker(offset: number) { - const marker = createFakeMarker( - term.buffer.active.baseY + term.buffer.active.cursorY + offset, - ); - markers.push(marker); - return marker; - }, - registerDecoration(options: { - marker?: { line: number }; - x: number; - width: number; - foregroundColor: string; - }) { - decorations.push(options); - const state = { - get line() { - return options.marker?.line ?? -1; - }, - isDisposed: false, - dispose() { - this.isDisposed = true; - }, - }; - decorationStates.push(state); - return state; - }, - refresh(start: number, end: number) { - refreshCalls.push({ start, end }); - }, + assert.equal(cellRgb(term, 0, "ERROR"), RED); + + highlighter.setRules(rule("#60A5FA"), true); + await highlighter.whenSettled(); + assert.equal(cellRgb(term, 0, "ERROR"), BLUE); + assert.equal(cellRgb(term, 1, "ERROR"), BLUE); + assert.match(visibleSerializer.serialize(), /38;2;96;165;250m/); + assert.doesNotMatch(visibleSerializer.serialize(), /38;2;248;113;113m/); + + highlighter.setRules(rule("#60A5FA"), false); + await highlighter.whenSettled(); + assert.equal(visibleSerializer.serialize(), "first ERROR\r\nsecond ERROR"); + + highlighter.dispose(); + term.dispose(); +}); + +test("keywords split across ordinary writes are colored after the line is complete", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "plain ERR"); + assert.notEqual(cellRgb(term, 0, "ERR"), RED); + await write(term, "OR text"); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + highlighter.dispose(); + term.dispose(); +}); + +test("overlapping expressions color each character at most once", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules([{ + id: "overlap", + label: "Overlap", + patterns: ["\\[ERROR\\]", "ERROR"], + color: "#F87171", + enabled: true, + }], true); + await write(term, "[ERROR]"); + assert.equal(firstRgbMatch(term, RED), 7); + highlighter.dispose(); + term.dispose(); +}); + +test("line anchors are evaluated per output line", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules([{ + id: "prompt", + label: "Prompt", + patterns: ["^#"], + color: "#F87171", + enabled: true, + }], true); + await write(term, "# one\r\n# two"); + assert.equal(cellRgb(term, 0, "#"), RED); + assert.equal(cellRgb(term, 1, "#"), RED); + highlighter.dispose(); + term.dispose(); +}); + +test("alternate-screen programs are not keyword-colored", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "before ERROR"); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + await write(term, "\x1b[?1049hTUI ERROR"); + assert.notEqual(cellRgb(term, 0, "ERROR"), RED); + await write(term, "\x1b[?1049l"); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + highlighter.dispose(); + term.dispose(); +}); + +test("byte output catches up once instead of staying permanently uncolored", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + + await new Promise((resolve) => { + term.write(new TextEncoder().encode("byte ERROR"), resolve); + }); + assert.notEqual(cellRgb(term, 0, "ERROR"), RED); + await new Promise((resolve) => setTimeout(resolve, 650)); + await highlighter.whenSettled(); + + assert.equal(cellRgb(term, 0, "ERROR"), RED); + assert.equal(highlighter.rebuildCount, 1); + highlighter.dispose(); + term.dispose(); +}); + +test("large output can bypass per-write coloring and is still recolored on a rule change", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + let bypass = true; + const highlighter = new KeywordHighlighter(term, { + shouldBypassHighlight: () => bypass, + }); + highlighter.setRules(rule(), true); + await write(term, `${"ERROR ".repeat(20)}tail`); + assert.notEqual(cellRgb(term, 0, "ERROR"), RED); + + bypass = false; + highlighter.setRules(rule("#60A5FA"), true); + await highlighter.whenSettled(); + assert.equal(cellRgb(term, 0, "ERROR"), BLUE); + + highlighter.dispose(); + term.dispose(); +}); + +test("bulk output skipped on the hot path is highlighted after output becomes quiet", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 8, scrollback: 100 }); + let bypass = true; + const highlighter = new KeywordHighlighter(term, { + shouldBypassHighlight: () => bypass, + }); + highlighter.setRules(rule(), true); + const history = Array.from({ length: 40 }, (_, index) => `line-${index} ERROR`).join("\r\n"); + await write(term, history); + assert.equal(highlighter.rebuildCount, 0, "hot-path flood must not recolor immediately"); + assert.notEqual(cellRgb(term, 0, "ERROR"), RED); + bypass = false; + + await new Promise((resolve) => setTimeout(resolve, 650)); + await highlighter.whenSettled(); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + assert.equal(highlighter.rebuildCount, 1); + highlighter.dispose(); + term.dispose(); +}); + +test("ordinary Enter does not rebuild a saturated scrollback", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 40, rows: 3, scrollback: 10 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + const history = Array.from({ length: 20 }, (_, index) => `line-${index} ERROR`).join("\r\n"); + noteTerminalOutputPressureData(term, history); + await write(term, history); + await new Promise((resolve) => setTimeout(resolve, 650)); + await highlighter.whenSettled(); + const rebuildsBeforeEnter = highlighter.rebuildCount; + + const prompt = "\r\nplain prompt # "; + noteTerminalOutputPressureData(term, prompt); + await write(term, prompt); + await new Promise((resolve) => setTimeout(resolve, 650)); + await highlighter.whenSettled(); + + assert.equal(highlighter.rebuildCount, rebuildsBeforeEnter); + highlighter.dispose(); + term.dispose(); +}); + +test("carriage-return rewrites rematch the current line", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "plain ERROR"); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + await write(term, "\rready OK "); + assert.equal(cellRgb(term, 0, "ERROR"), undefined); + assert.match(term.buffer.active.getLine(0)?.translateToString(true) ?? "", /ready OK/); + highlighter.dispose(); + term.dispose(); +}); + +test("rule changes keep scrollback position", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 40, rows: 4, scrollback: 40 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, Array.from({ length: 20 }, (_, index) => `line-${index} ERROR`).join("\r\n")); + term.scrollToLine(2); + const viewportY = term.buffer.active.viewportY; + + highlighter.setRules(rule("#60A5FA"), true); + await highlighter.whenSettled(); + assert.equal(term.buffer.active.viewportY, viewportY); + highlighter.dispose(); + term.dispose(); +}); + +test("rule changes preserve existing line timestamps", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 6, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await new Promise((resolve) => { + writeTerminalDataWithLineTimestamps(term, "stamp ERROR\r\nnext ERROR", resolve, { + timestampDate: new Date("2026-08-13T00:00:00.000Z"), + }); + }); + const markersBefore = term.markers.length; + + highlighter.setRules(rule("#60A5FA"), true); + await highlighter.whenSettled(); + assert.equal(term.markers.length, markersBefore); + assert.equal(cellRgb(term, 0, "ERROR"), BLUE); + highlighter.dispose(); + term.dispose(); +}); + +test("same-line appends still restore original colors when rules are disabled", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "ERROR"); + await write(term, " more"); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + highlighter.setRules(rule(), false); + await highlighter.whenSettled(); + assert.notEqual(cellRgb(term, 0, "ERROR"), RED); + highlighter.dispose(); + term.dispose(); +}); + +test("clear recolors the retained cursor row when rules stay enabled", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "keep ERROR"); + term.clear(); + const line = term.buffer.active.getLine(0)?.translateToString(true) ?? ""; + if (line.includes("ERROR")) { + assert.equal(cellRgb(term, 0, "ERROR"), RED); + } + highlighter.dispose(); + term.dispose(); +}); + +test("clear restores highlighted retained cells before dropping originals", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "ERROR stays"); + term.clear(); + highlighter.setRules(rule(), false); + await highlighter.whenSettled(); + const line = term.buffer.active.getLine(0)?.translateToString(true) ?? ""; + if (line.includes("ERROR")) { + assert.notEqual(cellRgb(term, 0, "ERROR"), RED); + } + highlighter.dispose(); + term.dispose(); +}); + +test("application reset clears highlight state with the visible terminal", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "old ERROR"); + term.reset(); + await write(term, "new plain"); + assert.equal(highlighter.serializeAddon.serialize(), "new plain"); + highlighter.dispose(); + term.dispose(); +}); + +test("8-digit plugin hex colors keep RGB and ignore alpha", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules([{ + id: "plugin-alpha", + label: "Error", + patterns: ["ERROR"], + color: "#F8717180", + enabled: true, + providerId: "plugin.demo", + }], true); + await write(term, "plain ERROR text"); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + highlighter.dispose(); + term.dispose(); +}); + +test("plugin scans stay within the bounded match budget", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules([{ + id: "plugin-dots", + label: "Dots", + patterns: ["."], + color: "#F87171", + enabled: true, + providerId: "plugin.demo", + }], true); + await write(term, "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"); + assert.ok(firstRgbMatch(term, RED) <= 256); + highlighter.dispose(); + term.dispose(); +}); + +test("Enter does not refresh already highlighted history rows", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "existing ERROR"); + const refreshed: Array<[number, number]> = []; + const originalRefresh = term.refresh.bind(term); + term.refresh = (start, end) => { + refreshed.push([start, end]); + originalRefresh(start, end); }; - - return { - term, - decorations, - decorationStates, - markers, - refreshCalls, - handlers, - getTranslateCount: () => translateCount, - getTranslatedLineIndexes: () => [...translatedLineIndexes], - getActiveDecorationCount: () => decorationStates.filter((state) => !state.isDisposed).length, - resetTranslateCount: () => { - translateCount = 0; - translatedLineIndexes.length = 0; - }, - resetRefreshCalls: () => { - refreshCalls.length = 0; - }, - setLineText: (lineY: number, text: string) => { - lines[lineY] = createLineAtIndex(text, lineY); - }, - }; -} - -test("setRules immediately highlights a newly added rule against visible terminal text", () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorations } = createFakeTerminal("hello DEPLOY world"); - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - highlighter.dispose(); - - assert.deepEqual(decorations.map(({ x, width, foregroundColor }) => ({ x, width, foregroundColor })), [ - { x: 6, width: 6, foregroundColor: "#F87171" }, - ]); - } finally { - raf.restore(); - } + await write(term, "\r\nplain prompt # "); + assert.equal(cellRgb(term, 0, "ERROR"), RED); + assert.ok(refreshed.every(([start]) => start >= 1), JSON.stringify(refreshed)); + highlighter.dispose(); + term.dispose(); }); -test("marker reindexing moves keyword decorations to the current buffer line", () => { - const raf = installAnimationFrameQueue(); - try { - const { term } = createFakeTerminal("hello DEPLOY world"); - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - - const internals = highlighter as unknown as { - lineDecorations: Map; - syncLineDecorationIndex: (force?: boolean) => void; - }; - const state = internals.lineDecorations.get(0); - assert.ok(state); - state.marker.line = 1; - - internals.syncLineDecorationIndex(true); - - assert.equal(internals.lineDecorations.has(0), false); - assert.equal(internals.lineDecorations.get(1), state); - assert.equal(state.indexedLine, 1); - highlighter.dispose(); - } finally { - raf.restore(); - } +test("a keyword written on a saturated scrollback is still colored", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 20, rows: 3, scrollback: 2 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, Array.from({ length: 8 }, (_, index) => `pad-${index}`).join("\r\n")); + await write(term, "\r\nline ERROR"); + assert.equal(cellRgb(term, term.buffer.active.baseY + term.buffer.active.cursorY, "ERROR") + ?? cellRgb(term, term.buffer.active.length - 1, "ERROR") + ?? cellRgb(term, term.buffer.active.length - 2, "ERROR"), RED); + highlighter.dispose(); + term.dispose(); }); -test("plugin rules use the RE2 matcher while saved user rules retain JavaScript regex behavior", () => { - const raf = installAnimationFrameQueue(); - const originalError = console.error; - console.error = () => {}; - try { - const userTerminal = createFakeTerminal("aa"); - const userHighlighter = new KeywordHighlighter(userTerminal.term as never); - userHighlighter.setRules([{ - id: "user", - label: "User", - patterns: ["(a)\\1"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - userHighlighter.dispose(); - assert.equal(userTerminal.decorations.length, 1); - - const pluginTerminal = createFakeTerminal("aa"); - const pluginHighlighter = new KeywordHighlighter(pluginTerminal.term as never); - pluginHighlighter.setRules([{ - id: "plugin:rule", - label: "Plugin", - patterns: ["(a)\\1"], - color: "#F87171", - enabled: true, - providerId: "plugin", - }], true); - raf.flush(); - pluginHighlighter.dispose(); - assert.equal(pluginTerminal.decorations.length, 0); - } finally { - console.error = originalError; - raf.restore(); - } +test("scrolling during a rule change catch-up recolors newly visible rows", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 40, rows: 4, scrollback: 80 }); + let bypass = true; + const highlighter = new KeywordHighlighter(term, { + shouldBypassHighlight: () => bypass, + }); + highlighter.setRules(rule(), true); + await write(term, Array.from({ length: 30 }, (_, index) => `line-${index} ERROR`).join("\r\n")); + bypass = false; + highlighter.setRules(rule("#60A5FA"), true); + term.scrollToLine(0); + assert.equal(cellRgb(term, 0, "ERROR"), BLUE); + await highlighter.whenSettled(); + highlighter.dispose(); + term.dispose(); }); -test("plugin patterns retain independent overlapping match semantics", () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorations } = createFakeTerminal("error code"); - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "plugin:overlap", - label: "Overlap", - patterns: ["error", "error code"], - color: "#F87171", - enabled: true, - providerId: "plugin", - }], true); - raf.flush(); - highlighter.dispose(); - assert.deepEqual(decorations.map(({ x, width }) => ({ x, width })), [{ x: 0, width: 10 }]); - - const shifted = createFakeTerminal("abab"); - const shiftedHighlighter = new KeywordHighlighter(shifted.term as never); - shiftedHighlighter.setRules([{ - id: "plugin:shifted-overlap", - label: "Shifted overlap", - patterns: ["aba", "bab"], - color: "#F87171", - enabled: true, - providerId: "plugin", - }], true); - raf.flush(); - shiftedHighlighter.dispose(); - assert.deepEqual(shifted.decorations.map(({ x, width }) => ({ x, width })), [{ x: 0, width: 4 }]); - } finally { - raf.restore(); - } +test("catch-up does not hang when the terminal enters the alternate screen", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term, { + shouldBypassHighlight: () => true, + }); + highlighter.setRules(rule(), true); + await write(term, "queued ERROR"); + await write(term, "\x1b[?1049hTUI"); + await Promise.race([ + highlighter.whenSettled(), + new Promise((_, reject) => setTimeout(() => reject(new Error("whenSettled hung")), 200)), + ]); + highlighter.dispose(); + term.dispose(); }); -test("plugin highlight work stays bounded at the maximum active rule budget", () => { - const raf = installAnimationFrameQueue(); - try { - const { term } = createFakeTerminalFromLines(Array.from({ length: 51 }, (_, index) => ({ - text: "x".repeat(80), - isWrapped: index > 0, - }))); - const highlighter = new KeywordHighlighter(term as never); - const rules = Array.from({ length: 16 }, (_, rule) => ({ - id: `plugin:${rule}`, - label: `Plugin ${rule}`, - patterns: [`missing-${rule}-a`, `missing-${rule}-b`], - color: "#F87171", - enabled: true, - providerId: "plugin", - })); - const startedAt = performance.now(); - highlighter.setRules(rules, true); - const compiledRules = (highlighter as unknown as { - compiledRules: Array<{ forEachMatch: (text: string, onMatch: (start: number, length: number) => boolean | void) => void }>; - }).compiledRules; - let matcherCalls = 0; - for (const compiledRule of compiledRules) { - const match = compiledRule.forEachMatch; - compiledRule.forEachMatch = (text, onMatch) => { - matcherCalls += 1; - match(text, onMatch); - }; - } - raf.flush(); - const elapsedMs = performance.now() - startedAt; - assert.equal(compiledRules.length, 32); - assert.equal(matcherCalls, 32); - assert.ok(elapsedMs < 1_000, `maximum plugin highlight workload took ${elapsedMs.toFixed(1)}ms`); - highlighter.dispose(); - } finally { - raf.restore(); - } +test("partial grapheme matches still color the whole cell", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 5, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules([{ + id: "letter-e", + label: "E", + patterns: ["e"], + color: "#F87171", + enabled: true, + }], true); + await write(term, "e\u0301"); + assert.equal(term.buffer.active.getLine(0)?.getCell(0)?.getFgColor(), RED); + highlighter.dispose(); + term.dispose(); }); -test("plugin match output is capped for a high-frequency wrapped logical line", () => { - const raf = installAnimationFrameQueue(); - try { - const { term } = createFakeTerminalFromLines(Array.from({ length: 51 }, (_, index) => ({ - text: "x".repeat(80), - isWrapped: index > 0, - }))); - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules(Array.from({ length: 16 }, (_, rule) => ({ - id: `plugin:dense-${rule}`, - label: `Dense ${rule}`, - patterns: [".", "x"], - color: "#F87171", - enabled: true, - providerId: "plugin", - })), true); - const compiledRules = (highlighter as unknown as { - compiledRules: Array<{ forEachMatch: (text: string, onMatch: (start: number, length: number) => boolean | void) => void }>; - }).compiledRules; - let deliveredMatches = 0; - for (const compiledRule of compiledRules) { - const match = compiledRule.forEachMatch; - compiledRule.forEachMatch = (text, onMatch) => match(text, (start, length) => { - deliveredMatches += 1; - return onMatch(start, length); - }); - } - const startedAt = performance.now(); - raf.flush(); - const elapsedMs = performance.now() - startedAt; - assert.equal(deliveredMatches, MAX_PLUGIN_DECORATION_MATCHES_PER_LOGICAL_LINE); - assert.ok(elapsedMs < 1_000, `dense plugin highlight workload took ${elapsedMs.toFixed(1)}ms`); - highlighter.dispose(); - } finally { - raf.restore(); - } +test("wrapped matches stay on the same logical line", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 8, rows: 6, scrollback: 20 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + await write(term, "xx ERROR"); + assert.equal(cellRgb(term, 0, "ER") === RED || cellRgb(term, 1, "ROR") === RED, true); + highlighter.dispose(); + term.dispose(); }); -test("plugin rules reject empty-match patterns before viewport scanning", () => { - const raf = installAnimationFrameQueue(); - try { - const { term } = createFakeTerminalFromLines(Array.from({ length: 51 }, (_, index) => ({ - text: "x".repeat(80), - isWrapped: index > 0, - }))); - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "plugin:empty", - label: "Empty", - patterns: ["a*", "a?", "^$"], - color: "#F87171", - enabled: true, - providerId: "plugin", - }], true); - assert.equal((highlighter as unknown as { compiledRules: unknown[] }).compiledRules.length, 0); - raf.flush(); - highlighter.dispose(); - } finally { - raf.restore(); +test("identical flood lines are all colored after quiet catch-up", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 12, scrollback: 40 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + const line = "2026-08-13 INFO worker=1 WARN ERROR failed from 10.2.0.1 payload=xxxxxxxx"; + for (let index = 0; index < 6; index += 1) { + noteTerminalOutputPressureData(term, `${line}\r\n`); + await write(term, `${line}\r\n`); } + const flood = Array.from({ length: 48 }, () => line).join("\r\n"); + noteTerminalOutputPressureData(term, flood); + await write(term, flood); + await new Promise((resolve) => setTimeout(resolve, 650)); + await highlighter.whenSettled(); + assert.deepEqual(uncoloredKeywordLines(term, "ERROR", RED), []); + highlighter.dispose(); + term.dispose(); }); -test("output-driven viewport changes defer keyword highlight scans", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, handlers, getTranslateCount, resetTranslateCount } = createFakeTerminal("hello DEPLOY world", { - lineCount: 20, - }); - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - resetTranslateCount(); - - term.buffer.active.length = 40; - term.buffer.active.baseY = 20; - term.buffer.active.viewportY = 20; - term.buffer.active.cursorY = 2; - handlers.writeParsed?.(); - handlers.render?.(); - - assert.equal(getTranslateCount(), 0); - - await new Promise((resolve) => { setTimeout(resolve, 220); }); - assert.ok(getTranslateCount() > 0); - highlighter.dispose(); - } finally { - raf.restore(); +test("saturated flood does not rematch the pinned viewport on each write", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 6, scrollback: 8 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + const line = "2026-08-13 INFO worker=1 WARN ERROR failed from 10.2.0.1"; + const chunk = Array.from({ length: 16 }, () => line).join("\r\n"); + for (let index = 0; index < 4; index += 1) { + noteTerminalOutputPressureData(term, chunk); + await write(term, chunk); } + assert.equal(highlighter.rebuildCount, 0); + const viewportY = term.buffer.active.viewportY; + assert.notEqual(cellRgb(term, viewportY, "ERROR"), RED); + assert.notEqual(cellRgb(term, viewportY + 2, "ERROR"), RED); + highlighter.dispose(); + term.dispose(); }); -test("user scroll reuses persistent prehighlighted lines without delayed scans", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, handlers, getTranslateCount, resetTranslateCount } = createFakeTerminal("hello DEPLOY world", { - lineCount: 80, - }); - term.rows = 30; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - resetTranslateCount(); - - term.buffer.active.viewportY = 10; - handlers.scroll?.(); - handlers.render?.(); - - assert.equal(getTranslateCount(), 0); - - await new Promise((resolve) => { setTimeout(resolve, 130); }); - assert.equal(getTranslateCount(), 0); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("distant user scroll synchronously highlights only the target viewport", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslatedLineIndexes, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 220 }); - term.rows = 30; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - resetTranslateCount(); - - term.buffer.active.baseY = 190; - term.buffer.active.viewportY = 120; - handlers.scroll?.(); - - assert.deepEqual( - getTranslatedLineIndexes(), - Array.from({ length: term.rows }, (_, index) => 120 + index), - "the destination viewport should be indexed before the scroll event returns", - ); - - await new Promise((resolve) => { setTimeout(resolve, 130); }); - assert.equal(getTranslatedLineIndexes().length, term.rows); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("user scrollback browsing stays synchronous during a write burst", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslatedLineIndexes, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 220 }); - term.rows = 30; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - resetTranslateCount(); - - for (let index = 0; index < 6; index += 1) { - handlers.writeParsed?.(); - } - resetTranslateCount(); - term.buffer.active.baseY = 190; - term.buffer.active.viewportY = 120; - handlers.scroll?.(); - - assert.deepEqual( - getTranslatedLineIndexes(), - Array.from({ length: term.rows }, (_, index) => 120 + index), - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("continuous distant scrolls do not scan skipped viewport ranges", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslatedLineIndexes, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 260 }); - term.rows = 30; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - resetTranslateCount(); - - term.buffer.active.baseY = 230; - term.buffer.active.viewportY = 120; - handlers.scroll?.(); - term.buffer.active.viewportY = 180; - handlers.scroll?.(); - - assert.deepEqual( - getTranslatedLineIndexes(), - [ - ...Array.from({ length: term.rows }, (_, index) => 120 + index), - ...Array.from({ length: term.rows }, (_, index) => 180 + index), - ], - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("persistent highlights remain until xterm disposes their markers", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getActiveDecorationCount, - markers, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 200 }); - term.rows = 3; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - assert.equal(getActiveDecorationCount(), 9); - - term.buffer.active.baseY = 170; - term.buffer.active.viewportY = 120; - handlers.scroll?.(); - assert.equal(getActiveDecorationCount(), 12); - - markers[0].dispose(); - handlers.scroll?.(); - assert.equal(getActiveDecorationCount(), 11); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("persistent highlight lookup follows uniform scrollback marker shifts", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getActiveDecorationCount, - getTranslateCount, - markers, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 30 }); - term.rows = 3; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - markers[0].dispose(); - for (const marker of markers) { - if (!marker.isDisposed) marker.line -= 1; - } - resetTranslateCount(); - - term.buffer.active.baseY = 27; - term.buffer.active.viewportY = 0; - handlers.scroll?.(); - - assert.equal(getTranslateCount(), term.rows); - assert.equal(getActiveDecorationCount(), 8); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("persistent marker index synchronization stays constant-time", () => { - const raf = installAnimationFrameQueue(); - try { - const { term, handlers } = createFakeTerminal("hello DEPLOY world", { lineCount: 400 }); - term.rows = 30; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - term.buffer.active.baseY = 370; - for (const viewportY of [120, 180, 240, 300]) { - term.buffer.active.viewportY = viewportY; - handlers.scroll?.(); - } - - fakeMarkerLineReadCount = 0; - handlers.scroll?.(); - - assert.ok( - fakeMarkerLineReadCount < 10, - `expected constant marker reads, got ${fakeMarkerLineReadCount}`, - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("persistent highlights stay bounded for broad matching rules", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getActiveDecorationCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 2_000 }); - term.rows = 30; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - term.buffer.active.baseY = 1_970; - for (let viewportY = 120; viewportY <= 1_800; viewportY += term.rows) { - term.buffer.active.viewportY = viewportY; - handlers.scroll?.(); - } - - const expectedLimit = Math.min( - XTERM_PERFORMANCE_CONFIG.highlighting.maxPersistentDecorationLines, - Math.max( - XTERM_PERFORMANCE_CONFIG.highlighting.minPersistentDecorationLines, - term.rows * XTERM_PERFORMANCE_CONFIG.highlighting.persistentDecorationViewports, - ), - ); - assert.equal(getActiveDecorationCount(), expectedLimit); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("external marker reset invalidates persistent highlight coverage", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getActiveDecorationCount, - getTranslateCount, - markers, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 9 }); - term.rows = 3; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - for (const marker of [...markers]) marker.dispose(); - resetTranslateCount(); - - handlers.scroll?.(); - - assert.equal(getTranslateCount(), term.rows); - assert.equal(getActiveDecorationCount(), term.rows); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("in-place redraw removes a persistent highlight when text stops matching", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getActiveDecorationCount, - setLineText, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 9 }); - term.rows = 3; - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - assert.equal(getActiveDecorationCount(), 9); - - setLineText(1, "hello SAFE world 1"); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 120); }); - raf.flush(); - - assert.equal(getActiveDecorationCount(), 8); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("overlapping scroll rescans write-dirtied lines instead of clearing them", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getActiveDecorationCount, - setLineText, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 12 }); - term.rows = 4; - term.buffer.active.viewportY = 0; - term.buffer.active.baseY = 0; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - assert.equal(getActiveDecorationCount(), 12); - - const internals = highlighter as unknown as { - lastRenderRange: { start: number; end: number } | null; - addDirtyRange: (start: number, end: number) => void; - dirtySegments: Array<{ start: number; end: number }>; - }; - assert.ok(internals.lastRenderRange); - - // Simulate an in-place redraw that dirtied an overlapping line, then a - // one-row scroll that cancels the pending write refresh. Scroll must still - // rescan that dirty overlap. - setLineText(1, "hello SAFE world 1"); - internals.addDirtyRange(1, 1); - assert.ok(internals.dirtySegments.length > 0); - term.buffer.active.viewportY = 1; - handlers.scroll?.(); - raf.flush(); - - assert.equal( - getActiveDecorationCount(), - 11, - "overlapping scroll should rescan write-dirtied lines in the overlap", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("Enter-driven scroll does not dispose nearby keyword decorations", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers } = createFakeTerminal("hello DEPLOY world", { - lineCount: 40, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - - // Idle Enter: onScroll before onWriteParsed. Persistence keeps nearby - // highlights mounted instead of pruning them as user-scroll leftovers. - handlers.data?.("\r"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "Enter-driven scroll should not dispose keyword decorations still on screen", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("user scroll during Enter keeps prior highlights mounted", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - decorationStates, - handlers, - getTranslatedLineIndexes, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { - lineCount: 80, - }); - term.rows = 3; - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - - handlers.data?.("\r"); - handlers.writeParsed?.(); - term.buffer.active.viewportY = 10; - resetTranslateCount(); - handlers.scroll?.(); - - assert.ok( - getTranslatedLineIndexes().some((lineY) => lineY >= 10 && lineY < 20), - "scrollback browsing during Enter should synchronously scan newly revealed lines", - ); - assert.ok( - decorationStates.some((state) => !state.isDisposed && state.line >= 10 && state.line < 13), - "scrollback browsing during Enter should apply highlights on newly revealed lines", - ); - raf.flush(); - - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "scroll during Enter should keep prior persistent highlights", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("Enter does not defer a user scroll back to the bottom", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslatedLineIndexes, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 80 }); - term.rows = 3; - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - - handlers.data?.("\r"); - term.buffer.active.viewportY = 10; - handlers.scroll?.(); - resetTranslateCount(); - - // Pressing End while the Enter guard is active returns to the bottom - // without changing the output position or waiting for a remote write. - term.buffer.active.viewportY = 20; - handlers.scroll?.(); - - assert.ok( - getTranslatedLineIndexes().some((lineY) => lineY >= 20), - "scrolling back to the bottom during Enter should scan synchronously", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("output during Enter does not cancel an active scrollback browse", () => { - const raf = installAnimationFrameQueue(); - try { - const { term, handlers } = createFakeTerminal("hello DEPLOY world", { lineCount: 80 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - - handlers.data?.("\r"); - term.buffer.active.viewportY = 10; - const internals = highlighter as unknown as { - pendingRefreshReason: "scroll" | "write" | "full"; - }; - // Model a scroll refresh that is pending while the user is browsing - // scrollback, then let remote output move the bottom of the buffer. - internals.pendingRefreshReason = "scroll"; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.writeParsed?.(); - - assert.equal( - internals.pendingRefreshReason, - "scroll", - "remote output must not reclassify an active scrollback browse as Enter output", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("large output delays keyword highlight scans until output quiets", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, handlers, getTranslateCount, resetTranslateCount } = createFakeTerminal("hello DEPLOY world", { - lineCount: 40, - }); - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - resetTranslateCount(); - - noteTerminalOutputPressureData( - term as never, - "x\n".repeat(Math.ceil(TERMINAL_LONG_LINE_PRESSURE_BYTES / 2)), - ); - handlers.writeParsed?.(); - raf.flush(); - - assert.equal(getTranslateCount(), 0); - - // Bulk path no longer schedules per-write scans (Tabby has no keyword work). - // A single quiet-window catch-up applies decorations after largeOutput ends. - await new Promise((resolve) => { setTimeout(resolve, 700); }); - raf.flush(); - assert.ok(getTranslateCount() > 0); - highlighter.dispose(); - resetTerminalOutputPressure(term as never); - } finally { - raf.restore(); - } -}); - -test("Enter cancels queued scroll work before large-output deferral", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - decorationStates, - handlers, - getTranslateCount, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - resetTranslateCount(); - - handlers.data?.("\r"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - noteTerminalOutputPressureData( - term as never, - "x\n".repeat(Math.ceil(TERMINAL_LONG_LINE_PRESSURE_BYTES / 2)), - ); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - const disposedDecorationCount = existingDecorations.filter(({ isDisposed }) => isDisposed).length; - const translateCountBeforeQuiet = getTranslateCount(); - highlighter.dispose(); - resetTerminalOutputPressure(term as never); - assert.equal( - disposedDecorationCount, - 0, - "large Enter output should not leave a queued scroll prune behind", - ); - assert.equal(translateCountBeforeQuiet, 0, "large output should wait for the quiet catch-up scan"); - } finally { - raf.restore(); - } -}); - -test("Enter replaces a queued write refresh with input-quiet work", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslateCount, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - resetTranslateCount(); - - const internals = highlighter as unknown as { lastRefreshTime: number }; - internals.lastRefreshTime = Number.NEGATIVE_INFINITY; - handlers.writeParsed?.(); - handlers.data?.("\r"); - handlers.writeParsed?.(); - resetTranslateCount(); - raf.flush(); - - assert.equal( - getTranslateCount(), - 0, - "the pre-Enter write frame should not scan during the input quiet window", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("Enter dirty work continues after a queued full refresh", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - decorationStates, - handlers, - setLineText, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const originalDecoration = decorationStates.find(({ line }) => line === 22); - assert.ok(originalDecoration); - - handlers.resize?.(); - handlers.data?.("\r"); - setLineText(22, "redrawn without a keyword"); - handlers.writeParsed?.(); - // Idle Enter suppresses decoration mutation until the Enter guard clears - // (~600ms) so prompt redraw cannot flash still-visible keywords. - await new Promise((resolve) => { setTimeout(resolve, 850); }); - raf.flush(); - - const originalDisposed = originalDecoration.isDisposed; - highlighter.dispose(); - assert.equal( - originalDisposed, - true, - "Enter changes should be consumed after a queued full refresh completes", - ); - } finally { - raf.restore(); - } -}); - -test("continuous Enter output lets multi-frame refreshes finish", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslatedLineIndexes, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 140 }); - term.rows = 100; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - resetTranslateCount(); - - const internals = highlighter as unknown as { - lastRefreshTime: number; - lastUserInputAt: number; - }; - handlers.data?.("\r"); - internals.lastUserInputAt = Number.NEGATIVE_INFINITY; - - const originalPerformance = globalThis.performance; - let simulatedNow = 0; - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: { - now: () => { - simulatedNow += 5; - return simulatedNow; - }, - }, - }); - try { - for (let index = 0; index < 3; index += 1) { - internals.lastRefreshTime = Number.NEGATIVE_INFINITY; - handlers.writeParsed?.(); - raf.flushOne(); - } - } finally { - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: originalPerformance, - }); - } - - const reachedViewportEnd = getTranslatedLineIndexes().includes(98); - highlighter.dispose(); - assert.ok( - reachedViewportEnd, - "continuation work should reach the end of a large viewport during ongoing output", - ); - } finally { - raf.restore(); - } -}); - -test("large output cancels active Enter continuation work until quiet", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslateCount, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 140 }); - term.rows = 100; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - - const internals = highlighter as unknown as { - lastRefreshTime: number; - lastUserInputAt: number; - }; - handlers.data?.("\r"); - internals.lastUserInputAt = Number.NEGATIVE_INFINITY; - internals.lastRefreshTime = Number.NEGATIVE_INFINITY; - - const originalPerformance = globalThis.performance; - let simulatedNow = 0; - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: { - now: () => { - simulatedNow += 5; - return simulatedNow; - }, - }, - }); - try { - handlers.writeParsed?.(); - raf.flushOne(); - } finally { - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: originalPerformance, - }); - } - - noteTerminalOutputPressureData( - term as never, - "x\n".repeat(Math.ceil(TERMINAL_LONG_LINE_PRESSURE_BYTES / 2)), - ); - handlers.writeParsed?.(); - resetTranslateCount(); - raf.flushOne(); - const scansDuringPressure = getTranslateCount(); - highlighter.dispose(); - resetTerminalOutputPressure(term as never); - - assert.equal( - scansDuringPressure, - 0, - "large output should cancel continuation scans until the quiet catch-up", - ); - } finally { - raf.restore(); - } -}); - -test("continuous Enter output still refreshes highlights periodically", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers, setLineText } = createFakeTerminal("no match", { - lineCount: 40, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - assert.equal(decorationStates.filter(({ isDisposed }) => !isDisposed).length, 0); - - handlers.data?.("\r"); - setLineText(22, "DEPLOY"); - const internals = highlighter as unknown as { - lastRefreshTime: number; - lastUserInputAt: number; - }; - // Sustained output must be a write burst, not spaced callbacks that look - // like a multi-batch prompt redraw. - internals.lastUserInputAt = Number.NEGATIVE_INFINITY; - const originalPerformance = globalThis.performance; - let simulatedNow = 0; - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: { - now: () => simulatedNow, - }, - }); - try { - for (let index = 0; index < 12; index += 1) { - simulatedNow += 10; - internals.lastRefreshTime = Number.NEGATIVE_INFINITY; - handlers.writeParsed?.(); - raf.flush(); - } - } finally { - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: originalPerformance, - }); - } - - assert.ok( - decorationStates.some(({ isDisposed }) => !isDisposed), - "ongoing write-burst output should not postpone new highlights until the stream stops", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("slow post-Enter output still applies highlights after the Enter guard", () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers, setLineText } = createFakeTerminal("no match", { - lineCount: 40, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - assert.equal(decorationStates.filter(({ isDisposed }) => !isDisposed).length, 0); - - const internals = highlighter as unknown as { - lastRefreshTime: number; - lastUserInputAt: number; - }; - const originalPerformance = globalThis.performance; - let simulatedNow = 1_000; - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: { - now: () => simulatedNow, - }, - }); - try { - handlers.data?.("\r"); - setLineText(22, "DEPLOY"); - internals.lastUserInputAt = Number.NEGATIVE_INFINITY; - // Intervals above WRITE_BURST_INTERVAL_MS never reach the burst - // threshold, and each write rearms the real idle timer. - for (let index = 0; index < 10; index += 1) { - simulatedNow += 80; - internals.lastRefreshTime = Number.NEGATIVE_INFINITY; - handlers.writeParsed?.(); - raf.flush(); - } - } finally { - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: originalPerformance, - }); - } - - assert.ok( - decorationStates.some(({ isDisposed }) => !isDisposed), - "steady non-bursty output should highlight after the Enter window, not wait for a pause", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("recent user input delays keyword highlight scans until typing is quiet", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, handlers, getTranslateCount, resetTranslateCount } = createFakeTerminal("hello DEPLOY world", { - lineCount: 40, - }); - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - resetTranslateCount(); - - handlers.data?.("a"); - handlers.writeParsed?.(); - raf.flush(); - - assert.equal(getTranslateCount(), 0); - - await new Promise((resolve) => { setTimeout(resolve, 120); }); - assert.equal(getTranslateCount(), 0); - - await new Promise((resolve) => { setTimeout(resolve, 100); }); - assert.ok(getTranslateCount() > 0); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("pressing Enter keeps unchanged keyword decorations mounted", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers } = createFakeTerminal("hello DEPLOY world", { - lineCount: 40, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - - handlers.data?.("\r"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "unchanged decorations should remain mounted while Enter output settles", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("pasted Enter remains protected when more input arrives before output", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers } = createFakeTerminal("hello DEPLOY world", { - lineCount: 40, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - - handlers.data?.("\u001b[200~echo DEPLOY\r\u001b[201~"); - handlers.data?.("x"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "a submitted Enter should stay protected until its output is processed", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("multi-command Enter protection survives earlier buffer movement until idle", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers } = createFakeTerminal("hello DEPLOY world", { - lineCount: 400, - }); - term.rows = 3; - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - - const internals = highlighter as unknown as { - dirtyAllInRenderRange: boolean; - enterInputPending: boolean; - lastBufferSnapshot: unknown; - readBufferSnapshot: () => unknown; - refreshViewport: (reason: "write") => void; - }; - for (let index = 0; index < 250; index += 1) { - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - internals.dirtyAllInRenderRange = true; - internals.refreshViewport("write"); - } - internals.lastBufferSnapshot = internals.readBufferSnapshot(); - const retainedDecorations = decorationStates.filter(({ isDisposed }) => !isDisposed); - assert.ok(retainedDecorations.length > 64); - - handlers.data?.("\u001b[200~echo one\r\necho two\r\n\u001b[201~"); - for (let index = 0; index < 12; index += 1) { - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 50); }); - } - - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - assert.equal( - retainedDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "continuous Enter output should postpone decoration pruning until idle", - ); - assert.equal(internals.enterInputPending, true); - - await new Promise((resolve) => { setTimeout(resolve, 700); }); - assert.equal(internals.enterInputPending, false, "Enter protection should end after output is idle"); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("a new Enter cancels the previous output idle deadline", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, handlers } = createFakeTerminal("hello DEPLOY world"); - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const internals = highlighter as unknown as { enterInputPending: boolean }; - - handlers.data?.("\r"); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 400); }); - handlers.data?.("\r"); - await new Promise((resolve) => { setTimeout(resolve, 250); }); - - assert.equal( - internals.enterInputPending, - true, - "the previous command's idle timer should not clear a newer Enter", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("pressing Enter avoids rescanning overscan edges", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslatedLineIndexes, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - resetTranslateCount(); - - handlers.data?.("\r"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - const scannedLines = getTranslatedLineIndexes(); - assert.ok(scannedLines.includes(22)); - assert.equal(scannedLines.includes(15), false); - assert.equal(scannedLines.includes(29), false); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("non-Enter input still detects redraws away from the cursor", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers, setLineText } = createFakeTerminal("hello DEPLOY world", { - lineCount: 60, - }); - term.rows = 10; - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 9; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const originalDecoration = decorationStates.find(({ line }) => line === 20); - assert.ok(originalDecoration); - - handlers.data?.("a"); - setLineText(20, "redrawn without a keyword"); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - assert.equal(originalDecoration.isDisposed, true); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("Enter input still detects redraws away from the cursor", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers, setLineText } = createFakeTerminal("hello DEPLOY world", { - lineCount: 60, - }); - term.rows = 10; - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 9; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const originalDecoration = decorationStates.find(({ line }) => line === 20); - assert.ok(originalDecoration); - - handlers.data?.("\r"); - setLineText(20, "redrawn without a keyword"); - handlers.writeParsed?.(); - // Idle Enter defers decoration dispose/apply until the Enter guard clears. - await new Promise((resolve) => { setTimeout(resolve, 850); }); - raf.flush(); - - assert.equal(originalDecoration.isDisposed, true); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("write-only scrolling batches pruning but stays hard-bounded", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates } = createFakeTerminal("hello DEPLOY world", { - lineCount: 400, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - - const internals = highlighter as unknown as { - dirtyAllInRenderRange: boolean; - refreshViewport: (reason: "write") => void; - }; - for (let index = 0; index < 250; index += 1) { - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - internals.dirtyAllInRenderRange = true; - internals.refreshViewport("write"); - } - - const liveDuringOutput = decorationStates.filter(({ isDisposed }) => !isDisposed).length; - assert.ok(liveDuringOutput > 64, "active output should not prune at the soft threshold"); - assert.ok(liveDuringOutput <= 256, "active output should remain hard-bounded"); - - await new Promise((resolve) => { setTimeout(resolve, 700); }); - assert.ok( - decorationStates.filter(({ isDisposed }) => !isDisposed).length <= 64, - "idle cleanup should return retained decorations to the soft bound", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("late Enter output stays protected after the pending hint expires", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers } = createFakeTerminal("hello DEPLOY world", { - lineCount: 40, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const retainedDecorations = decorationStates.filter(({ isDisposed }) => !isDisposed); - assert.ok(retainedDecorations.length > 0); - - handlers.data?.("\r"); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 650); }); - - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - assert.equal( - retainedDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "late Enter output should treat its queued scroll as output-driven", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("late Enter output detects content shifts after scrollback saturates", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates, handlers, markers } = createFakeTerminal("hello DEPLOY world", { - lineCount: 40, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const retainedDecorations = decorationStates.filter(({ isDisposed }) => !isDisposed); - assert.ok(retainedDecorations.length > 0); - - handlers.data?.("\r"); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 650); }); - - for (const marker of markers) { - if (!marker.isDisposed) marker.line -= 1; - } - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - assert.equal( - retainedDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "marker shifts should identify delayed output when buffer positions are saturated", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("write pruning enforces a hard bound and delays soft cleanup until idle", async () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorationStates } = createFakeTerminal("hello DEPLOY world", { - lineCount: 400, - }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - - const internals = highlighter as unknown as { - dirtyAllInRenderRange: boolean; - refreshViewport: (reason: "write") => void; - }; - for (let index = 0; index < 250; index += 1) { - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - internals.dirtyAllInRenderRange = true; - internals.refreshViewport("write"); - } - - const liveDuringOutput = decorationStates.filter(({ isDisposed }) => !isDisposed).length; - const disposedDuringHardTrim = decorationStates.filter(({ isDisposed }) => isDisposed).length; - assert.ok(liveDuringOutput > 64, "active output should retain more than the soft bound"); - assert.ok(liveDuringOutput <= 256, "active output should stay within the hard bound"); - - const originalPerformance = globalThis.performance; - let simulatedNow = 0; - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: { - now: () => { - simulatedNow += 5; - return simulatedNow; - }, - }, - }); - try { - term.rows = 30; - internals.dirtyAllInRenderRange = true; - internals.refreshViewport("write"); - } finally { - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: originalPerformance, - }); - } - raf.flush(); - term.rows = 3; - - assert.equal( - decorationStates.filter(({ isDisposed }) => isDisposed).length, - disposedDuringHardTrim, - "continuation scans should not trigger another prune below the hard bound", - ); - await new Promise((resolve) => { setTimeout(resolve, 700); }); - assert.ok( - decorationStates.filter(({ isDisposed }) => !isDisposed).length <= 64, - "idle cleanup should return retained decorations to the bounded range", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("pressing Enter does not repaint after keyword markers move", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - markers, - refreshCalls, - handlers, - resetRefreshCalls, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - resetRefreshCalls(); - - for (const marker of markers) marker.line += 1; - handlers.data?.("\r"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - - assert.deepEqual(refreshCalls, []); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("idle Enter scroll before writeParsed does not rescan visible keywords", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - decorationStates, - handlers, - getTranslateCount, - resetTranslateCount, - refreshCalls, - resetRefreshCalls, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - - // Ordinary write refreshes clear lastRenderRange. An idle prompt then has no - // scroll coverage hint, so Enter echo onScroll (before writeParsed, Ubuntu RTT) - // would otherwise take the immediate user-scroll path and rescan the viewport. - const internals = highlighter as unknown as { - lastWriteAt: number; - lastRenderRange: { start: number; end: number } | null; - }; - internals.lastWriteAt = performance.now() - 10_000; - internals.lastRenderRange = null; - resetTranslateCount(); - resetRefreshCalls(); - - handlers.data?.("\r"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - - assert.equal( - getTranslateCount(), - 0, - "Enter-pending scroll before writeParsed must not rescan visible keywords", - ); - assert.deepEqual( - refreshCalls, - [], - "Enter-pending scroll before writeParsed must not force a keyword repaint", - ); - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "Enter-pending scroll must keep existing keyword decorations mounted", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("idle Enter scroll before buffer dims update does not rescan", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - decorationStates, - handlers, - getTranslateCount, - resetTranslateCount, - refreshCalls, - resetRefreshCalls, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - - const internals = highlighter as unknown as { - lastWriteAt: number; - lastRenderRange: { start: number; end: number } | null; - }; - internals.lastWriteAt = performance.now() - 10_000; - internals.lastRenderRange = null; - resetTranslateCount(); - resetRefreshCalls(); - - // Ubuntu RTT: onScroll can fire while length/baseY/cursor still match the - // last snapshot, so output-driven detection is false. Bottom-pinned Enter - // must still defer — requiring hasOutputDrivenViewportChange reopens flash. - handlers.data?.("\r"); - handlers.scroll?.(); - - assert.equal( - getTranslateCount(), - 0, - "Enter-pending bottom scroll without buffer-dim change must not rescan", - ); - assert.deepEqual( - refreshCalls, - [], - "Enter-pending bottom scroll without buffer-dim change must not repaint", - ); - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "Enter-pending bottom scroll must keep existing keyword decorations mounted", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("idle Enter prompt redraw does not repaint existing keyword rows", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - decorationStates, - handlers, - setLineText, - refreshCalls, - resetRefreshCalls, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - { - id: "prompt", - label: "Prompt", - patterns: ["~", "#"], - color: "#60A5FA", - enabled: true, - }, - ], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - resetRefreshCalls(); - - handlers.data?.("\r"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - // New prompt line matches custom ~/# rules — applying those decorations - // makes xterm repaint the full viewport and flashes still-visible keywords. - setLineText(22, "user@host:~# "); - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - raf.flush(); - - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "idle Enter must keep prior keyword decorations mounted", - ); - assert.deepEqual( - refreshCalls, - [], - "idle Enter prompt redraw must not register decorations that force a viewport repaint", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("idle Enter keeps suppression across split echo and prompt writes", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - decorationStates, - handlers, - setLineText, - refreshCalls, - resetRefreshCalls, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - { - id: "prompt", - label: "Prompt", - patterns: ["~", "#"], - color: "#60A5FA", - enabled: true, - }, - ], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - resetRefreshCalls(); - - handlers.data?.("\r"); - // Batch 1: newline echo advances the buffer. - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 40); }); - raf.flush(); - - // Batch 2: prompt text for the same idle Enter (custom ~/# matches). - setLineText(22, "user@host:~# "); - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 40); }); - raf.flush(); - - // Batch 3: trailing mode/control write — still the same prompt redraw, - // not sustained command output. - handlers.writeParsed?.(); - await new Promise((resolve) => { setTimeout(resolve, 220); }); - raf.flush(); - - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "split idle-Enter writes must keep prior keyword decorations mounted", - ); - assert.deepEqual( - refreshCalls, - [], - "a three-batch idle prompt must not register decorations that flash the viewport", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("pre-Enter write burst does not lift idle-Enter decoration suppression", () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - decorationStates, - handlers, - setLineText, - refreshCalls, - resetRefreshCalls, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([ - { - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }, - { - id: "prompt", - label: "Prompt", - patterns: ["~", "#"], - color: "#60A5FA", - enabled: true, - }, - ], true); - raf.flush(); - const existingDecorations = [...decorationStates]; - assert.ok(existingDecorations.length > 0); - resetRefreshCalls(); - - const internals = highlighter as unknown as { - recentWriteBurst: number; - lastWriteAt: number; - lastBurstDecayAt: number; - }; - const originalPerformance = globalThis.performance; - let simulatedNow = 1_000; - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: { - now: () => simulatedNow, - }, - }); - try { - internals.recentWriteBurst = 8; - internals.lastWriteAt = simulatedNow; - internals.lastBurstDecayAt = simulatedNow; - - handlers.data?.("\r"); - term.buffer.active.viewportY += 1; - term.buffer.active.baseY += 1; - term.buffer.active.length += 1; - handlers.scroll?.(); - simulatedNow += 5; - handlers.writeParsed?.(); - raf.flush(); - - setLineText(22, "user@host:~# "); - simulatedNow += 5; - handlers.writeParsed?.(); - raf.flush(); - - simulatedNow += 5; - handlers.writeParsed?.(); - raf.flush(); - } finally { - Object.defineProperty(globalThis, "performance", { - configurable: true, - value: originalPerformance, - }); - } - - assert.equal( - existingDecorations.filter(({ isDisposed }) => isDisposed).length, - 0, - "stale pre-Enter burst must not dispose still-visible keyword decorations", - ); - assert.deepEqual( - refreshCalls, - [], - "stale pre-Enter burst must not register prompt decorations that flash the viewport", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("Enter without write clears pending so later user scroll can highlight", async () => { - const raf = installAnimationFrameQueue(); - try { - const { - term, - handlers, - getTranslateCount, - resetTranslateCount, - } = createFakeTerminal("hello DEPLOY world", { lineCount: 40 }); - term.buffer.active.viewportY = 20; - term.buffer.active.baseY = 20; - term.buffer.active.cursorY = 2; - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "deploy", - label: "Deploy", - patterns: ["DEPLOY"], - color: "#F87171", - enabled: true, - }], true); - raf.flush(); - - const internals = highlighter as unknown as { - enterInputPending: boolean; - lastWriteAt: number; - lastRenderRange: { start: number; end: number } | null; - }; - internals.lastWriteAt = performance.now() - 10_000; - internals.lastRenderRange = null; - - // Enter with no echo/writeParsed (echo off / stalled PTY). - handlers.data?.("\r"); - assert.equal(internals.enterInputPending, true); - - await new Promise((resolve) => { setTimeout(resolve, 700); }); - assert.equal( - internals.enterInputPending, - false, - "Enter protection must time out when no write arrives", - ); - - // User browsing scrollback after the timed-out Enter guard. - resetTranslateCount(); - term.buffer.active.viewportY = 10; - handlers.scroll?.(); - raf.flush(); - - assert.ok( - getTranslateCount() > 0, - "user scroll after timed-out Enter must scan newly revealed scrollback", - ); - highlighter.dispose(); - } finally { - raf.restore(); - } -}); - -test("long-line pressure avoids scanning across a whole soft-wrapped logical line", () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorations } = createFakeTerminalFromLines([ - { text: "abc", isWrapped: false }, - { text: "XYZ", isWrapped: true }, - ]); - noteTerminalOutputPressureData( - term as never, - "x".repeat(TERMINAL_LONG_LINE_PRESSURE_BYTES), - ); - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "wrapped", - label: "Wrapped", - patterns: ["abcXYZ"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - highlighter.dispose(); - resetTerminalOutputPressure(term as never); - - assert.deepEqual(decorations, []); - } finally { - raf.restore(); - } -}); - -test("wrapped highlight scanning falls back when the logical line exceeds the scan cap", () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorations } = createFakeTerminalFromLines([ - { text: `${"a".repeat(TERMINAL_AUX_LONG_LINE_SCAN_LIMIT_CHARS)}ZZ`, isWrapped: false }, - { text: "tail", isWrapped: true }, - ]); - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "capped-wrapped", - label: "Capped wrapped", - patterns: ["ZZtail"], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - highlighter.dispose(); - resetTerminalOutputPressure(term as never); - - assert.deepEqual(decorations, []); - } finally { - raf.restore(); - } -}); - -test("oversized wrapped blocks skip plugin rules instead of resetting their per-line budget", () => { - const raf = installAnimationFrameQueue(); - try { - const { term, decorations } = createFakeTerminalFromLines([ - { text: "a".repeat(TERMINAL_AUX_LONG_LINE_SCAN_LIMIT_CHARS), isWrapped: false }, - { text: "PLUGIN", isWrapped: true }, - ]); - const highlighter = new KeywordHighlighter(term as never); - highlighter.setRules([{ - id: "plugin:oversized", - label: "Oversized", - patterns: ["PLUGIN"], - color: "#F87171", - enabled: true, - providerId: "plugin", - }], true); - raf.flush(); - highlighter.dispose(); - assert.deepEqual(decorations, []); - } finally { - raf.restore(); - } -}); - -test("wrapped highlight scanning stops before walking an oversized soft-wrapped line", () => { - const raf = installAnimationFrameQueue(); - try { - const lineText = "a".repeat(80); - const { term, decorations, getLineCount } = createFakeTerminalFromLargeWrappedBlock({ - lineCount: 30_000, - lineText, - viewportY: 29_990, - rows: 3, - }); - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "wrapped", - label: "Wrapped", - patterns: [`${lineText}${lineText}`], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - highlighter.dispose(); - resetTerminalOutputPressure(term as never); - - assert.deepEqual(decorations, []); - assert.ok( - getLineCount() < 3_000, - `expected capped wrapped scan, got ${getLineCount()} getLine calls`, - ); - } finally { - raf.restore(); - } -}); - -test("scroll refresh reuses wrapped scan misses across visible rows", () => { - const raf = installAnimationFrameQueue(); - try { - const lineText = "a".repeat(80); - const { - term, - handlers, - getLineCount, - resetGetLineCount, - } = createFakeTerminalFromLargeWrappedBlock({ - lineCount: 30_000, - lineText, - viewportY: 29_000, - rows: 30, - }); - const highlighter = new KeywordHighlighter(term as never); - const rules: KeywordHighlightRule[] = [ - { - id: "wrapped", - label: "Wrapped", - patterns: [`${lineText}${lineText}`], - color: "#F87171", - enabled: true, - }, - ]; - - highlighter.setRules(rules, true); - raf.flush(); - resetGetLineCount(); - - term.buffer.active.viewportY = 29_500; - handlers.scroll?.(); - - assert.ok( - getLineCount() < 1_000, - `expected scroll chunk to share wrapped scan cache, got ${getLineCount()} getLine calls`, - ); - highlighter.dispose(); - resetTerminalOutputPressure(term as never); - } finally { - raf.restore(); - } +test("recycled identical flood rows are recolored on catch-up", async () => { + const term = new XTerm({ allowProposedApi: true, cols: 80, rows: 8, scrollback: 12 }); + const highlighter = new KeywordHighlighter(term); + highlighter.setRules(rule(), true); + const line = "2026-08-13 INFO worker=1 WARN ERROR failed from 10.2.0.1"; + const flood = Array.from({ length: 40 }, () => line).join("\r\n"); + noteTerminalOutputPressureData(term, flood); + await write(term, flood); + noteTerminalOutputPressureData(term, flood); + await write(term, flood); + await new Promise((resolve) => setTimeout(resolve, 650)); + await highlighter.whenSettled(); + assert.deepEqual(uncoloredKeywordLines(term, "ERROR", RED), []); + highlighter.dispose(); + term.dispose(); }); diff --git a/components/terminal/keywordHighlight.ts b/components/terminal/keywordHighlight.ts index 6047e7350..d1460c27c 100644 --- a/components/terminal/keywordHighlight.ts +++ b/components/terminal/keywordHighlight.ts @@ -1,2036 +1,882 @@ +import { SerializeAddon } from "@xterm/addon-serialize"; +import type { IBufferLine, IDisposable, IMarker, Terminal as XTerm } from "@xterm/xterm"; -import { Terminal as XTerm, IDecoration, IDisposable, IMarker, IBuffer, IBufferLine } from "@xterm/xterm"; -import { KeywordHighlightRule } from "../../types"; - -import { XTERM_PERFORMANCE_CONFIG } from "../../infrastructure/config/xtermPerformance"; -import { checkRegexSafetyPattern } from "../../lib/regexSafety"; import { isSafePluginDecorationPattern } from "../../domain/pluginTerminalProviders"; -import { TERMINAL_AUX_LONG_LINE_SCAN_LIMIT_CHARS } from "./runtime/terminalFlowConstants"; -import { getTerminalOutputPressure } from "./runtime/terminalOutputPressure"; -import { compileRe2RangeMatcher, forEachNonEmptyRegexMatch, type NonEmptyRangeVisitor } from "./keywordHighlightRegex"; - -/** Pre-compiled rule with regex ready for matching */ -interface CompiledRule { - forEachMatch: (text: string, onMatch: NonEmptyRangeVisitor) => void; - color: string; - priority: number; - plugin: boolean; -} +import { checkRegexSafetyPattern } from "../../lib/regexSafety"; +import type { KeywordHighlightRule } from "../../types"; +import { XTERM_PERFORMANCE_CONFIG } from "../../infrastructure/config/xtermPerformance"; +import { readPluginTerminalBufferText } from "./pluginTerminalBufferText"; +import { compileRe2RangeMatcher, forEachNonEmptyRegexMatch } from "./keywordHighlightRegex"; +import { shouldDegradeTerminalKeywordHighlight } from "./runtime/terminalOutputPressure"; type RuntimeKeywordHighlightRule = KeywordHighlightRule & { readonly providerId?: string }; -export const MAX_PLUGIN_DECORATION_SCAN_CHARS = 4_096; -export const MAX_PLUGIN_DECORATION_MATCHES_PER_LOGICAL_LINE = 256; - -interface CachedDecorationRange { - x: number; - width: number; - color: string; +type CompiledPattern = { priority: number; -} + rgb: number; + plugin: boolean; + visit(text: string, onMatch: (start: number, length: number) => boolean | void): void; +}; -interface LogicalDecorationRange { - start: number; - length: number; - color: string; - priority: number; -} - -interface DirtyLineSegment { +type HighlightMatch = { start: number; end: number; -} + priority: number; + rgb: number; +}; -interface LineDecorationState { - marker: IMarker; - decorations: IDecoration[]; - signature: string; - indexedLine: number; -} - -type RefreshReason = "scroll" | "write" | "full"; - -interface BufferSnapshot { +type InternalBufferLine = { length: number; - baseY: number; - viewportY: number; - cursorAbsoluteY: number; - viewportProbe: readonly ViewportProbeSample[]; -} + isWrapped: boolean; + _data: Uint32Array; +}; -interface ViewportProbeSample { - lineY: number; - hash: number; -} +type LineOriginals = { + fg: Uint32Array; + content: Uint32Array; + mask: Uint8Array; + fingerprint: string; +}; -interface WrappedBlockContext { - logicalLineText: string; - segmentBounds: Map; - matchRanges?: readonly LogicalDecorationRange[]; -} +type LogicalLine = { + startY: number; + endY: number; + text: string; + cellAtStringOffset: Array<{ y: number; x: number }>; +}; -type WrappedBlockCacheEntry = WrappedBlockContext | null; +export type KeywordHighlighterOptions = { + shouldBypassHighlight?: () => boolean; + serializeAddon?: SerializeAddon; + canRebuild?: () => boolean; + shouldPreserveScrollback?: () => boolean; + onRestoringSelectionChange?: (restoring: boolean) => void; + onDidRebuild?: () => void; +}; -interface WrappedBlockScanCache { - contexts: Map; - cappedMiss: DirtyLineSegment | null; -} +const CELL_INDICES = 3; +const CELL_CONTENT = 0; +const CELL_FG = 1; +const STYLE_MASK = 0xfc000000; +const CM_RGB = 0x3000000; +const MAX_PLUGIN_HIGHLIGHT_SCAN_CHARS = 4_096; +const MAX_PLUGIN_HIGHLIGHT_MATCHES_PER_WRITE = 256; +const RECOLOR_SLICE_LINES = 32; +const RECOLOR_SLICE_BUDGET_MS = 4; +const BULK_WRITE_LINE_BREAKS = 8; +const MAX_LOGICAL_LINE_ROWS = 128; -/** Shared empty array for non-matching lines to avoid per-call allocations. */ -const EMPTY_RANGES: readonly CachedDecorationRange[] = Object.freeze([]); +const withRgbFg = (originalFg: number, rgb: number): number => ( + (originalFg & STYLE_MASK) | CM_RGB | (rgb & 0xffffff) +); -/** ASCII-only test — when true, string indices equal cell columns. */ -// eslint-disable-next-line no-control-regex -const RE_ASCII_ONLY = /^[\x00-\x7f]*$/; +const parseRgb = (color: string): number | null => { + const normalized = color.trim(); + const short = /^#([\da-f])([\da-f])([\da-f])$/i.exec(normalized); + // Plugin decorations accept #RRGGBBAA; cell fg is 24-bit, so drop alpha. + const full = /^#([\da-f]{2})([\da-f]{2})([\da-f]{2})(?:[\da-f]{2})?$/i.exec(normalized); + const components = full + ? full.slice(1) + : short + ? short.slice(1).map((component) => component.repeat(2)) + : null; + if (!components) return null; + return components.reduce((value, component) => ( + (value << 8) | Number.parseInt(component, 16) + ), 0); +}; -/** - * Manages terminal decorations for keyword highlighting. - * Uses persistent xterm.js markers so nearby indexed lines keep decorations - * across scrollback navigation without modifying the terminal data stream. - * Retention is bounded to protect xterm's marker listeners for broad rules. - */ -export class KeywordHighlighter implements IDisposable { - private term: XTerm; - private compiledRules: CompiledRule[] = []; - private lineDecorations = new Map(); - private markerLineOffset = 0; - private lineDecorationIndexNeedsRebuild = false; - private debounceTimer: NodeJS.Timeout | null = null; - /** Single quiet-window catch-up after bulk dumps (no per-write schedule). */ - private bulkPressureCatchUpTimer: NodeJS.Timeout | null = null; - private enterInputIdleTimer: NodeJS.Timeout | null = null; - private writePruneTimer: NodeJS.Timeout | null = null; - private animationFrameId: number | null = null; - private lastRefreshTime: number = 0; - private matchCache = new Map(); - private enabled: boolean = false; - private disposables: IDisposable[] = []; - private lastViewportY: number = -1; - private lastViewportRange: { start: number; end: number } | null = null; - private lastRenderRange: { start: number; end: number } | null = null; - private pendingRefreshReason: RefreshReason = "write"; - private dirtySegments: DirtyLineSegment[] = []; - private dirtyLineCount = 0; - private dirtyAllInRenderRange = false; - private activeRefreshViewport: DirtyLineSegment | null = null; - private pendingTerminalRefreshRange: DirtyLineSegment | null = null; - private lastBufferSnapshot: BufferSnapshot | null = null; - private recentWriteBurst = 0; - private lastWriteAt = 0; - private lastBurstDecayAt = 0; - private lastUserInputAt = 0; - private enterInputPending = false; - private enterQueuedWriteCancellationPending = false; - private enterViewportScanInProgress = false; - private enterViewportScanNeedsRepeat = false; - /** True while idle-Enter output should not mutate decorations (xterm full-viewport repaint flash). */ - private enterSuppressDecorationMutation = false; - /** - * Whether onWriteParsed has already observed the current Enter submission. - * Prompt redraw can span several writeParsed batches (control sequences, - * prompt text, mode sets); callback count is not a sustained-output signal. - */ - private enterWriteParsedSeen = false; - /** performance.now() when the current Enter started suppressing mutations. */ - private enterSuppressionStartedAt = 0; - /** Viewport browsing state before the latest scroll handler ran. */ - private wasBrowsingScrollback = false; - private static readonly DIRTY_SCAN_PADDING = XTERM_PERFORMANCE_CONFIG.highlighting.dirtyScanPadding; - private static readonly INPUT_QUIET_MS = XTERM_PERFORMANCE_CONFIG.highlighting.inputQuietMs; - private static readonly WRITE_BURST_INTERVAL_MS = 28; - private static readonly WRITE_BURST_DECAY_MS = 80; - private static readonly WRITE_BURST_THRESHOLD = 6; - private static readonly WRITE_BURST_OVERSCAN_SCALE = 0.35; - private static readonly WRITE_BURST_BUDGET_SCALE = 0.5; - private static readonly WRITE_BURST_CHUNK_SCALE = 0.5; - private static readonly WRITE_BURST_DEBOUNCE_MS = 180; - private static readonly WRITE_BURST_IMMEDIATE_MIN_INTERVAL_MS = 48; - private static readonly WRITE_BURST_HIGHLIGHT_PAUSE_MS = 260; - private static readonly ENTER_INPUT_GUARD_MS = 600; - private static readonly WRITE_PRUNE_IDLE_MS = 600; - - constructor(term: XTerm) { - this.term = term; - - // Hook into terminal events to trigger highlighting - this.disposables.push( - // When user scrolls, refresh visible area - this.term.onScroll((viewportY) => { - this.lastViewportY = viewportY; - this.triggerViewportChangeRefresh(); - }), - // User input should keep terminal echo responsive; highlight can catch up - // once typing pauses. - this.term.onData((data) => { - this.lastUserInputAt = performance.now(); - if (data.includes("\r") || data.includes("\n")) { - this.enterInputPending = true; - this.enterQueuedWriteCancellationPending = true; - // First prompt redraw after Enter must not register/dispose decorations: - // xterm repaints the full viewport on decoration mutation and flashes - // still-visible keyword highlights (custom ~/# rules make this obvious). - this.enterSuppressDecorationMutation = true; - this.enterWriteParsedSeen = false; - this.enterSuppressionStartedAt = performance.now(); - // Pre-Enter burst must not lift mute on a split prompt. Keep - // lastWriteAt so output-driven scroll detection still works before - // the first post-Enter updateWriteBurst. - this.recentWriteBurst = 0; - this.lastBurstDecayAt = 0; - // Time-bound Enter protection even when no echo/write arrives (echo - // off, stalled PTY). onWriteParsed re-arms this on each write. - this.scheduleEnterInputIdleClear(); - // Drop any pending user-scroll refresh so Enter echo cannot finish a - // scroll pass that rescans/repaints still-visible keyword decorations - // before onWriteParsed owns the write path (Ubuntu RTT). - if (this.pendingRefreshReason === "scroll" && !this.isBrowsingScrollback()) { - this.cancelQueuedRefreshSchedule(); - this.pendingRefreshReason = "write"; - } - } - }), - // When new data is written, refresh on the next frame so highlights land - // with the freshly rendered content instead of trailing behind it. - this.term.onWriteParsed(() => { - if (this.enterInputPending) { - this.scheduleEnterInputIdleClear(); - } - const isBrowsingScrollback = this.isBrowsingScrollback(); - const outputDrivenPendingScroll = - this.pendingRefreshReason === "scroll" - && !isBrowsingScrollback - && ( - this.hasOutputDrivenViewportChange() - ); - const cancelQueuedWriteForEnter = - this.enterQueuedWriteCancellationPending - && this.pendingRefreshReason === "write"; - // Convert output-driven auto-scroll to write refresh. Do not cancel a - // real user scrollback browse just because Enter write-path is active. - if (outputDrivenPendingScroll && this.pendingRefreshReason === "scroll") { - this.cancelQueuedRefreshSchedule(); - this.pendingRefreshReason = "write"; - } else if (cancelQueuedWriteForEnter) { - this.cancelQueuedRefreshSchedule(); - } - this.enterQueuedWriteCancellationPending = false; - const pressure = getTerminalOutputPressure(this.term); - if (pressure.background || pressure.longLine || pressure.largeOutput) { - if (this.pendingRefreshReason === "write") { - this.cancelQueuedRefreshSchedule(); - } - this.enterViewportScanInProgress = false; - this.enterViewportScanNeedsRepeat = false; - } - if (pressure.background) { - // Hidden panes: avoid immediate scans that fight xterm, but still arm a - // debounced refresh. Reveal only flushes writes/repaints — without a - // scheduled tick, decorations for hidden-pane output never apply if no - // further write/scroll/resize happens after show (Codex PR review). - this.updateWriteBurst(); - this.markVisibleRangeDirty(); - this.triggerRefresh("debounced", "write"); - return; - } - if ( - pressure.longLine - || pressure.largeOutput - ) { - this.updateWriteBurst(); - // Tabby has no keyword path. During bulk dumps do not schedule - // decoration work at all (debounced scans still compete with xterm). - // Mark dirty + one quiet catch-up after pressure drops. - this.markVisibleRangeDirty(); - this.scheduleBulkPressureCatchUp(); - return; - } - const inputProtectionActive = this.isInputProtectionActive(performance.now()); - if (inputProtectionActive || this.enterInputPending) { - if (this.enterInputPending) { - if (this.enterWriteParsedSeen) { - this.updateWriteBurst(); - // Multi-batch prompt redraw is still not command output. Keep - // decoration mute until a write burst or the Enter idle guard. - if (this.shouldLiftEnterDecorationSuppression()) { - this.enterSuppressDecorationMutation = false; - } - if (this.enterViewportScanInProgress) { - this.enterViewportScanNeedsRepeat = true; - } else { - const buffer = this.term.buffer.active; - this.addDirtyRange(buffer.viewportY, buffer.viewportY + this.term.rows - 1); - this.enterViewportScanInProgress = true; - } - } else { - this.enterWriteParsedSeen = true; - this.markDirtyFromWrite({ includeViewportProbe: false }); - // Index the viewport while muted so multi-frame Enter continuation - // can finish; decoration mutate stays suppressed for idle prompt. - const buffer = this.term.buffer.active; - this.addDirtyRange(buffer.viewportY, buffer.viewportY + this.term.rows - 1); - this.enterViewportScanInProgress = true; - } - } else { - this.updateWriteBurst(); - this.markVisibleRangeDirty(); - } - this.triggerRefresh(inputProtectionActive ? "debounced" : "immediate", "write"); - return; - } - this.markDirtyFromWrite(); - if (outputDrivenPendingScroll) { - this.markVisibleRangeDirty(); - } - this.triggerRefresh( - "immediate", - "write", - ); - }), - // Also refresh on resize as viewport content changes - this.term.onResize(() => { - this.syncLineDecorationIndex(true); - this.lastRenderRange = null; - this.triggerRefresh("debounced", "full"); - }), - // onRender fires after each render cycle - catch scrolls that onScroll might miss - this.term.onRender(() => { - // Only trigger refresh if viewport position changed - const currentViewportY = this.term.buffer.active?.viewportY ?? 0; - if (currentViewportY !== this.lastViewportY) { - this.lastViewportY = currentViewportY; - this.triggerViewportChangeRefresh(); - } - }) - ); - this.lastBufferSnapshot = this.readBufferSnapshot(); - this.wasBrowsingScrollback = this.isBrowsingScrollback(); - } - - public setRules(rules: readonly RuntimeKeywordHighlightRule[], enabled: boolean) { - this.enabled = enabled; - this.matchCache.clear(); - - // Pre-compile all patterns into regexes for better performance - // This avoids creating new RegExp objects on every viewport refresh - this.compiledRules = []; - for (const [ruleIndex, rule] of rules.entries()) { - if (!rule.enabled || rule.patterns.length === 0) continue; +const compilePatterns = ( + rules: readonly RuntimeKeywordHighlightRule[], + enabled: boolean, +): CompiledPattern[] => { + if (!enabled) return []; + const compiled: CompiledPattern[] = []; + for (const [priority, rule] of rules.entries()) { + if (!rule.enabled) continue; + const rgb = parseRgb(rule.color); + if (rgb === null) continue; + for (const pattern of rule.patterns) { + if (!pattern || checkRegexSafetyPattern(pattern).safe === false) continue; if (rule.providerId) { - const patterns = rule.patterns.filter((pattern) => { - if (!pattern) return false; - const safetyCheck = checkRegexSafetyPattern(pattern); - if (safetyCheck.safe === false) { - console.warn("[KeywordHighlight] Skipping unsafe regex pattern:", pattern, "reason:", safetyCheck.reason); - return false; - } - if (!isSafePluginDecorationPattern(pattern)) { - console.warn("[KeywordHighlight] Skipping unsupported plugin regex pattern:", pattern); - return false; - } - return true; - }); - for (const pattern of patterns) { - try { - const match = compileRe2RangeMatcher(pattern); - this.compiledRules.push({ - forEachMatch: (text, onMatch) => match(text.slice(0, MAX_PLUGIN_DECORATION_SCAN_CHARS), onMatch), - color: rule.color, - priority: ruleIndex, - plugin: true, - }); - } catch (err) { - console.error("Invalid plugin regex pattern:", pattern, err); - } + if (!isSafePluginDecorationPattern(pattern)) continue; + try { + const matcher = compileRe2RangeMatcher(pattern); + compiled.push({ + priority, + rgb, + plugin: true, + visit(text, onMatch) { + matcher(text, onMatch); + }, + }); + } catch { + // Invalid plugin rules are ignored at the display boundary. } continue; } - for (const pattern of rule.patterns) { - if (!pattern) continue; // Skip empty patterns — RegExp("") is valid but matches nothing useful - const safetyCheck = checkRegexSafetyPattern(pattern); - if (safetyCheck.safe === false) { - console.warn("[KeywordHighlight] Skipping unsafe regex pattern:", pattern, "reason:", safetyCheck.reason); - continue; - } - try { - const regex = new RegExp(pattern, 'gi'); - const forEachMatch = (text: string, onMatch: NonEmptyRangeVisitor) => { - forEachNonEmptyRegexMatch(regex, text, (match) => { - onMatch(match.index, match[0].length); - }); - }; - this.compiledRules.push({ - forEachMatch, - color: rule.color, - priority: ruleIndex, - plugin: false, - }); - } catch (err) { - console.error("Invalid regex pattern:", pattern, err); - } + try { + const regex = new RegExp(pattern, "gi"); + compiled.push({ + priority, + rgb, + plugin: false, + visit(text, onMatch) { + forEachNonEmptyRegexMatch(regex, text, (match) => onMatch(match.index, match[0].length)); + }, + }); + } catch { + // Invalid user rules are ignored. The settings UI also rejects them. } } - - // Clear existing and force an immediate refresh if enabling - this.clearDecorations(); - if (this.enabled && this.compiledRules.length > 0) { - this.triggerRefresh("immediate", "full"); - } } + return compiled; +}; - public dispose() { - this.clearDecorations(); - this.disposables.forEach(d => d.dispose()); - this.disposables = []; - if (this.debounceTimer) { - clearTimeout(this.debounceTimer); - this.debounceTimer = null; - } - if (this.bulkPressureCatchUpTimer) { - clearTimeout(this.bulkPressureCatchUpTimer); - this.bulkPressureCatchUpTimer = null; - } - if (this.enterInputIdleTimer) { - clearTimeout(this.enterInputIdleTimer); - this.enterInputIdleTimer = null; - } - if (this.writePruneTimer) { - clearTimeout(this.writePruneTimer); - this.writePruneTimer = null; - } - if (this.animationFrameId !== null) { - cancelAnimationFrame(this.animationFrameId); - this.animationFrameId = null; - } - this.matchCache.clear(); - } +const getInternalLine = (line: IBufferLine | undefined): InternalBufferLine | null => { + if (!line) return null; + const view = line as IBufferLine & { _line?: InternalBufferLine; _data?: Uint32Array }; + if (view._line?._data) return view._line; + if (view._data) return view as InternalBufferLine; + return null; +}; - /** - * After bulk/large-output dumps, apply keyword decorations once output is - * quiet. Avoids per-write timer/rAF work during the flood (Tabby has none). - */ - private scheduleBulkPressureCatchUp(): void { - if (this.bulkPressureCatchUpTimer !== null) return; - const quietMs = Math.max( - 48, - XTERM_PERFORMANCE_CONFIG.highlighting.largeOutputQuietMs ?? 480, - ); - const tick = (): void => { - this.bulkPressureCatchUpTimer = null; - if (!this.enabled || this.compiledRules.length === 0) return; - const pressure = getTerminalOutputPressure(this.term); - // Only largeOutput is time-bounded. longLine stays sticky until a later - // short write updates pressure — waiting on it would poll forever after a - // single threshold-sized line with no follow-up (Codex review). - if (pressure.largeOutput) { - this.bulkPressureCatchUpTimer = setTimeout(tick, 50); - return; - } - this.markVisibleRangeDirty(); - // One catch-up scan after the dump — immediate so decorations appear - // without another full large-output debounce wait. - this.triggerRefresh("immediate", "write"); - }; - this.bulkPressureCatchUpTimer = setTimeout(tick, quietMs); - } - - /** Shared refresh execution for both rAF and timer callbacks. */ - private executeRefresh() { - // Cancel any stale rAF that will never fire (e.g. hidden tab) - if (this.animationFrameId !== null) { - cancelAnimationFrame(this.animationFrameId); - this.animationFrameId = null; - } - // Re-check state: may have changed since the refresh was scheduled - if (!this.enabled || this.compiledRules.length === 0) return; - if (this.term.buffer.active.type === 'alternate') { - if (this.lineDecorations.size > 0) this.clearDecorations(); - return; - } - this.lastRefreshTime = performance.now(); - const reason = this.pendingRefreshReason; - this.pendingRefreshReason = "write"; - this.refreshViewport(reason); - this.lastBufferSnapshot = this.readBufferSnapshot({ includeViewportProbe: reason !== "scroll" }); - } - - private clearDecorations() { - const hadDecorations = this.lineDecorations.size > 0; - for (const [lineY, state] of this.lineDecorations) { - this.disposeLineDecorations(lineY, state); - } - this.lineDecorations.clear(); - this.markerLineOffset = 0; - this.lineDecorationIndexNeedsRebuild = false; - this.lastViewportRange = null; - this.lastRenderRange = null; - this.clearDirtySegments(); - this.dirtyAllInRenderRange = false; - this.enterQueuedWriteCancellationPending = false; - this.enterViewportScanInProgress = false; - this.enterViewportScanNeedsRepeat = false; - this.enterSuppressDecorationMutation = false; - this.enterWriteParsedSeen = false; - this.enterSuppressionStartedAt = 0; - if (hadDecorations) { - this.term.refresh(0, this.term.rows - 1); - } - } - - private disposeLineDecorations(lineY: number, state?: LineDecorationState) { - const target = state ?? this.getLineDecorationState(lineY); - if (!target) return; - const removedLineY = this.removeLineDecorationState(target, lineY); - const markerLineBeforeDispose = target.marker.isDisposed ? -1 : target.marker.line; - target.decorations.forEach((decoration) => decoration.dispose()); - target.marker.dispose(); - const refreshLine = removedLineY ?? (markerLineBeforeDispose >= 0 ? markerLineBeforeDispose : lineY); - this.markTerminalRefreshNeeded(refreshLine); - } - - private removeLineDecorationState(target: LineDecorationState, lineHint?: number): number | null { - const indexedState = this.lineDecorations.get(target.indexedLine); - if (indexedState === target) { - this.lineDecorations.delete(target.indexedLine); - return target.marker.isDisposed - ? (lineHint ?? null) - : target.marker.line; - } - if (lineHint != null) { - const hinted = this.lineDecorations.get(this.toIndexedLine(lineHint)); - if (hinted === target) { - this.lineDecorations.delete(hinted.indexedLine); - return lineHint; - } - } - for (const [mappedLineY, mappedState] of this.lineDecorations) { - if (mappedState === target) { - this.lineDecorations.delete(mappedLineY); - return target.marker.isDisposed - ? (lineHint ?? null) - : target.marker.line; - } - } - return null; - } - - private buildRangesSignature(ranges: readonly CachedDecorationRange[]): string { - if (ranges.length === 0) return ""; - let signature = ""; - for (const range of ranges) { - signature += `${range.x}:${range.width}:${range.color};`; - } - return signature; - } - - private applyLineDecorations( - lineY: number, - ranges: readonly CachedDecorationRange[], - signature: string, - cursorAbsoluteY: number, - ) { - const offset = lineY - cursorAbsoluteY; - const marker = this.term.registerMarker(offset); - if (!marker) { - this.lineDecorations.delete(this.toIndexedLine(lineY)); - return; - } - - const decorations: IDecoration[] = []; - for (const range of ranges) { - const decoration = this.term.registerDecoration({ - marker, - x: range.x, - width: range.width, - foregroundColor: range.color, +const collectMatches = ( + text: string, + patterns: readonly CompiledPattern[], +): HighlightMatch[] => { + const matches: HighlightMatch[] = []; + let pluginMatchCount = 0; + for (const pattern of patterns) { + if (pattern.plugin && pluginMatchCount >= MAX_PLUGIN_HIGHLIGHT_MATCHES_PER_WRITE) continue; + const scanText = pattern.plugin ? text.slice(0, MAX_PLUGIN_HIGHLIGHT_SCAN_CHARS) : text; + pattern.visit(scanText, (start, length) => { + if (length <= 0) return; + matches.push({ + start, + end: start + length, + priority: pattern.priority, + rgb: pattern.rgb, }); - if (decoration) { - decorations.push(decoration); - } - } - - if (decorations.length === 0) { - marker.dispose(); - this.lineDecorations.delete(this.toIndexedLine(lineY)); - return; - } - - const state: LineDecorationState = { - marker, - decorations, - signature, - indexedLine: this.toIndexedLine(lineY), - }; - marker.onDispose(() => { - this.removeLineDecorationState(state, lineY); - this.lastRenderRange = null; - for (const decoration of decorations) { - if (!decoration.isDisposed) decoration.dispose(); - } + if (!pattern.plugin) return; + pluginMatchCount += 1; + return pluginMatchCount < MAX_PLUGIN_HIGHLIGHT_MATCHES_PER_WRITE; }); - this.lineDecorations.set(state.indexedLine, state); - this.markTerminalRefreshNeeded(lineY); + } + if (matches.length === 0) return matches; + matches.sort((left, right) => ( + left.start - right.start + || left.priority - right.priority + || right.end - left.end + )); + const accepted: HighlightMatch[] = []; + for (const match of matches) { + if (accepted.length === 0 || match.start >= accepted[accepted.length - 1].end) { + accepted.push(match); + } + } + return accepted; +}; + +const yieldToRenderer = (): Promise => new Promise((resolve) => setTimeout(resolve, 0)); + +/** + * Keyword highlighting mutates already-parsed cell foregrounds. Writes stay + * pristine, so ordinary Enter/output never rebuilds history, and serialize can + * restore the original colors without a second terminal. + */ +export class KeywordHighlighter implements IDisposable { + readonly serializeAddon: SerializeAddon; + rebuildCount = 0; + lastRebuildTimings: Record = {}; + + private readonly originals = new WeakMap(); + /** No-match rows only need a fingerprint; do not allocate cell snapshots. */ + private readonly fingerprints = new WeakMap(); + private readonly originalWrite: XTerm["write"]; + private readonly originalReset: XTerm["reset"]; + private readonly originalClear: XTerm["clear"]; + private readonly originalResize: XTerm["resize"]; + private readonly originalSerialize: SerializeAddon["serialize"]; + private readonly disposables: IDisposable[] = []; + private rules: readonly RuntimeKeywordHighlightRule[] = []; + private enabled = false; + private compiledPatterns: CompiledPattern[] = []; + private disposed = false; + private catchUpFrom: number | null = null; + private catchUpStartMarker: IMarker | null = null; + private catchUpTimer: ReturnType | null = null; + private catchUpDueAt = 0; + private catchUpPromise: Promise = Promise.resolve(); + private resolveCatchUp: (() => void) | null = null; + private catchUpCounted = false; + private catchUpRunning = false; + private catchUpGeneration = 0; + private ruleGeneration = 0; + private readonly coloredGeneration = new WeakMap(); + private lastViewportY = 0; + private lastBaseY = 0; + private hasOutput = false; + + get pendingPristineBytes(): number { + return 0; } - /** - * Build a mapping from string character index to terminal cell column. - * This handles wide characters (CJK, emoji) and combining characters correctly. - * - * For example, with "A中B": - * - String indices: 0='A', 1='中', 2='B' - * - Cell columns: 0='A', 1='中'(width 2), 3='B' - * - Result map: [0, 1, 3, 4] (includes end position) - */ - private buildStringToCellMap(line: IBufferLine): number[] { - const map: number[] = []; - let cellCol = 0; - - for (let col = 0; col < line.length; col++) { - const cell = line.getCell(col); - if (!cell) break; - - const chars = cell.getChars(); - const width = cell.getWidth(); - - // Skip continuation cells (width 0) - these are the 2nd cell of wide characters - if (width === 0) continue; - - if (chars.length > 0) { - // Map each character in this cell to the current cell column - for (let i = 0; i < chars.length; i++) { - map.push(cellCol); - } - } else { - // Empty cell (codepoint 0) — translateToString() outputs a space - // for it, so we must push one entry to keep the map aligned. - map.push(cellCol); - } - - cellCol += width; - } - - // Add final position for calculating end column of matches - map.push(cellCol); - - return map; + get isPristineBackpressured(): boolean { + return false; } - private triggerRefresh(mode: "immediate" | "debounced" | "continuation", reason: RefreshReason = "full") { - if (!this.enabled || this.compiledRules.length === 0) return; - this.pendingRefreshReason = this.mergeRefreshReason(this.pendingRefreshReason, reason); - - // Optimization: Disable highlighting in Alternate Buffer (e.g. Vim, Htop) - // These apps manage their own highlighting and have rapid repaints. - if (this.term.buffer.active.type === 'alternate') { - if (this.lineDecorations.size > 0) { - this.clearDecorations(); - } - return; + constructor( + private readonly term: XTerm, + private readonly options: KeywordHighlighterOptions = {}, + ) { + if (options.serializeAddon) { + this.serializeAddon = options.serializeAddon; + } else { + this.serializeAddon = new SerializeAddon(); + term.loadAddon(this.serializeAddon); } - - const now = performance.now(); - if (this.shouldDeferRefreshForWriteBurst(mode, reason, now)) { - // Only cancel a pending rAF when the merged reason is still "write" - // (pure write burst, no scroll pending). If a scroll event has been - // merged, keep the rAF alive so the viewport highlight runs on time. - if (this.pendingRefreshReason === "write" && this.animationFrameId !== null) { - cancelAnimationFrame(this.animationFrameId); - this.animationFrameId = null; - } - if (this.debounceTimer) { - clearTimeout(this.debounceTimer); - } - const delay = this.getWriteBurstDeferDelay(now); - this.debounceTimer = setTimeout(() => { - this.debounceTimer = null; - this.executeRefresh(); - }, delay); - return; - } - - // xterm emits onScroll synchronously before it queues the viewport refresh. - // Reconcile only the newly visible lines in that event so decorations are - // registered before the next frame, including for distant scrollbar jumps. - if (mode === "immediate" && reason === "scroll") { - if (this.animationFrameId !== null) { - cancelAnimationFrame(this.animationFrameId); - this.animationFrameId = null; - } - if (this.debounceTimer) { - clearTimeout(this.debounceTimer); - this.debounceTimer = null; - } - this.executeRefresh(); - return; - } - - if (mode === "continuation") { - if (this.animationFrameId !== null) { - return; - } - this.animationFrameId = requestAnimationFrame(() => { - this.animationFrameId = null; - if (this.debounceTimer) { - clearTimeout(this.debounceTimer); - this.debounceTimer = null; + this.originalSerialize = this.serializeAddon.serialize.bind(this.serializeAddon); + this.serializeAddon.serialize = (serializeOptions) => { + this.restoreBuffer(); + try { + return this.originalSerialize(serializeOptions); + } finally { + if (!this.disposed && this.compiledPatterns.length > 0) { + this.recolorVisible(); + this.markCatchUp(0); + this.scheduleCatchUp(); } - this.executeRefresh(); - }); - // Hidden/background tabs may pause rAF. Keep a timer fallback so - // continuation does not stall indefinitely. - if (!this.debounceTimer) { - this.debounceTimer = setTimeout(() => { - this.debounceTimer = null; - this.executeRefresh(); - }, this.getAdaptiveHighlightingProfile().debounceMs); } - return; - } - - if (mode === "immediate") { - if (this.animationFrameId !== null) { - // Scroll should preempt queued continuation/write work. - // Cancel the pending frame and reschedule with current viewport intent. - if (reason === "scroll") { - cancelAnimationFrame(this.animationFrameId); - this.animationFrameId = null; - if (this.debounceTimer) { - clearTimeout(this.debounceTimer); - this.debounceTimer = null; - } - } else { - // Throttle non-scroll immediate refreshes when a frame is already pending. - // Don't clear the debounce timer here — in a hidden tab rAF never - // fires, so the fallback timer is the only path that will run. + }; + this.originalWrite = term.write.bind(term); + this.originalReset = term.reset.bind(term); + this.originalClear = term.clear.bind(term); + this.originalResize = term.resize.bind(term); + (term as XTerm & { __netcattyKeywordHighlighter?: KeywordHighlighter }) + .__netcattyKeywordHighlighter = this; + term.write = this.write; + term.reset = this.reset; + term.clear = this.clear; + term.resize = this.resize; + this.lastViewportY = term.buffer.active.viewportY; + this.lastBaseY = term.buffer.active.baseY; + this.disposables.push( + term.onScroll(() => { + if (!this.hasPendingCatchUp()) { + this.rememberScrollPosition(); return; } - } - if (this.animationFrameId !== null) { - return; - } - const now = performance.now(); - const minInterval = this.getAdaptiveHighlightingProfile(now).immediateMinIntervalMs; - if (reason !== "scroll" && now - this.lastRefreshTime < minInterval) { - // Too soon — fall through to debounced path instead of dropping - this.triggerRefresh("debounced", reason); - return; - } - this.animationFrameId = requestAnimationFrame(() => { - this.animationFrameId = null; - // rAF fired — cancel the fallback timer to avoid a redundant refresh - if (this.debounceTimer) { - clearTimeout(this.debounceTimer); - this.debounceTimer = null; - } - this.executeRefresh(); + if (this.isOutputDrivenScroll()) return; + this.recolorVisible(); + }), + term.buffer.onBufferChange(() => { + if (this.term.buffer.active.type !== "normal") return; + if (this.hasPendingCatchUp()) this.scheduleCatchUp(); + }), + ); + } + + setRules(rules: readonly RuntimeKeywordHighlightRule[], enabled: boolean): void { + if (this.disposed) return; + const nextRules = rules.map((rule) => ({ ...rule, patterns: [...rule.patterns] })); + const nextSignature = JSON.stringify([enabled, nextRules]); + const currentSignature = JSON.stringify([this.enabled, this.rules]); + if (nextSignature === currentSignature) return; + this.rules = nextRules; + this.enabled = enabled; + this.compiledPatterns = compilePatterns(this.rules, this.enabled); + if (!this.hasOutput) return; + if (this.catchUpTimer !== null) { + clearTimeout(this.catchUpTimer); + this.catchUpTimer = null; + } + this.catchUpGeneration += 1; + this.ruleGeneration += 1; + this.catchUpCounted = true; + this.rebuildCount += 1; + const started = performance.now(); + this.recolorVisible(); + this.markCatchUp(0); + if (!this.resolveCatchUp) { + this.catchUpPromise = new Promise((resolve) => { + this.resolveCatchUp = resolve; }); - // Arm a debounced fallback: rAF does not fire in background/hidden - // tabs (Chromium throttles it), so the timer ensures highlights - // still update for ongoing output. If rAF fires first it cancels - // this timer (see above), preventing a double refresh. - if (!this.debounceTimer) { - this.debounceTimer = setTimeout(() => { - this.debounceTimer = null; - this.executeRefresh(); - }, this.getAdaptiveHighlightingProfile().debounceMs); - } - return; } - - if (this.animationFrameId !== null) { - return; - } - - if (this.debounceTimer) { - clearTimeout(this.debounceTimer); - } - - const inputQuietDelay = reason === "write" - ? this.getInputProtectionRemainingMs(performance.now()) - : 0; - const delay = Math.max(this.getAdaptiveHighlightingProfile().debounceMs, inputQuietDelay); - this.debounceTimer = setTimeout(() => { - this.debounceTimer = null; - this.executeRefresh(); - }, delay); + void this.runCatchUp(); + this.lastRebuildTimings = { total: performance.now() - started }; } - private triggerViewportChangeRefresh() { - const isBrowsingScrollback = this.isBrowsingScrollback(); - // End (or other jump-to-bottom) while Enter is pending: we were browsing - // scrollback and just landed on the bottom without waiting for echo. - // Distinguish that from idle-Enter echo still pinned at the bottom. - const returningToBottomFromScrollback = - this.wasBrowsingScrollback && !isBrowsingScrollback; - this.wasBrowsingScrollback = isBrowsingScrollback; - // Enter echo often emits onScroll before onWriteParsed. After an idle gap - // lastWriteAt looks stale and lastRenderRange is usually null (cleared by - // the previous write refresh), so the output-driven scroll path would - // synchronously rescan the viewport and flash keywords still on screen. - // Keep real scrollback browsing synchronous; defer bottom-pinned Enter - // echo even when buffer dims have not updated yet (Ubuntu RTT). Do not - // require hasOutputDrivenViewportChange — that hole reopened the flash. - if ( - this.enterInputPending - && !isBrowsingScrollback - && !returningToBottomFromScrollback - ) { - if (this.pendingRefreshReason === "scroll") { - this.cancelQueuedRefreshSchedule(); - this.pendingRefreshReason = "write"; - } - this.markVisibleRangeDirty(); - return; + async whenSettled(): Promise { + while (!this.disposed) { + if (this.term.buffer.active.type !== "normal") return; + const catchUp = this.catchUpPromise; + await catchUp; + if (this.catchUpTimer === null && !this.catchUpRunning) return; + if (this.term.buffer.active.type !== "normal") return; + await yieldToRenderer(); } - const now = performance.now(); - const isOutputDrivenViewportChange = - !isBrowsingScrollback && - this.lastWriteAt > 0 && - now - this.lastWriteAt <= KeywordHighlighter.WRITE_BURST_HIGHLIGHT_PAUSE_MS; - if (isOutputDrivenViewportChange || (!isBrowsingScrollback && this.isWriteBurstActive(now))) { - this.markVisibleRangeDirty(); - this.triggerRefresh("debounced", "write"); - return; - } - - this.triggerRefresh("immediate", "scroll"); } - private refreshViewport(reason: RefreshReason) { - // Safety check just in case - if (!this.term?.buffer?.active) return; + async prepareForSerialization(): Promise { + // serialize() restores originals itself. Do not wait for flood catch-up. + } + + async waitForPristineBackpressure(): Promise {} + + syncScrollback(): void {} + + mirrorViewportScroll(_lines: number): void {} + + mirrorScrollbackWipe(): void {} + + deferMutationDuringRebuild(_run: () => Promise | void): boolean { + return false; + } + + dispose(): void { + if (this.disposed) return; + this.disposed = true; + this.term.write = this.originalWrite; + this.term.reset = this.originalReset; + this.term.clear = this.originalClear; + this.term.resize = this.originalResize; + this.serializeAddon.serialize = this.originalSerialize; + const patchedTerm = this.term as XTerm & { __netcattyKeywordHighlighter?: KeywordHighlighter }; + if (patchedTerm.__netcattyKeywordHighlighter === this) { + delete patchedTerm.__netcattyKeywordHighlighter; + } + if (this.catchUpTimer !== null) clearTimeout(this.catchUpTimer); + this.catchUpTimer = null; + this.resolveCatchUp?.(); + this.resolveCatchUp = null; + this.catchUpStartMarker?.dispose(); + this.catchUpStartMarker = null; + for (const disposable of this.disposables) disposable.dispose(); + } + + private readonly write: XTerm["write"] = (data, callback) => { + if (this.disposed) return this.originalWrite(data, callback); + const startedOnNormal = this.term.buffer.active.type === "normal"; + if (!startedOnNormal && this.compiledPatterns.length === 0 && !this.hasPendingCatchUp()) { + return this.originalWrite(data, callback); + } + this.hasOutput = startedOnNormal || this.hasOutput; + if (this.compiledPatterns.length === 0 && !this.hasPendingCatchUp() && startedOnNormal) { + return this.originalWrite(data, callback); + } + const startY = this.term.buffer.active.baseY + this.term.buffer.active.cursorY; + const bypass = !startedOnNormal || this.shouldBypassWrite(data); + if (bypass) { + if (startedOnNormal && (this.enabled || this.compiledPatterns.length > 0 || this.hasPendingCatchUp())) { + this.markCatchUp(startY); + this.scheduleCatchUp(); + } + return this.originalWrite(data, () => { + if (this.term.buffer.active.type === "normal" && !startedOnNormal) { + if (this.enabled || this.compiledPatterns.length > 0) { + this.markCatchUp(0); + this.scheduleCatchUp(); + } + } + callback?.(); + }); + } + // In-place CR / backspace / EL / ICH / DCH rewrite the current row. + // `\r\n` is a line advance and must not restore/repaint the previous prompt. + const eraseInLine = typeof data === "string" && /\x1b\[[\d;]*[K@PMLGHf]/.test(data); // eslint-disable-line no-control-regex + const rewritesCurrentLine = typeof data === "string" + && (/\r(?!\n)/.test(data) || data.includes("\x08") || eraseInLine); + const startsWithLineAdvance = typeof data === "string" && /^(?:\r\n|\n)/.test(data); + if (this.compiledPatterns.length > 0 && rewritesCurrentLine) { + this.restorePhysicalLine(startY); + } + const writeMarker = this.term.registerMarker(0); + return this.originalWrite(data, () => { + const active = this.term.buffer.active; + if (active.type === "normal") { + const endY = active.baseY + active.cursorY; + if (!writeMarker || writeMarker.isDisposed) { + if (this.enabled || this.compiledPatterns.length > 0) { + this.markCatchUp(0); + this.scheduleCatchUp(); + } + } else { + const fromY = startsWithLineAdvance ? Math.min(endY, writeMarker.line + 1) : writeMarker.line; + if (this.compiledPatterns.length === 0) { + if (this.hasStoredOriginalsInRange(fromY, endY)) { + this.markCatchUp(fromY); + this.scheduleCatchUp(); + } + } else { + this.recolorRange(fromY, endY, true, true); + } + } + } else if (startedOnNormal && (this.enabled || this.compiledPatterns.length > 0)) { + this.markCatchUp(writeMarker && !writeMarker.isDisposed ? writeMarker.line : 0); + this.scheduleCatchUp(); + } + writeMarker?.dispose(); + callback?.(); + }); + }; + + private readonly reset: XTerm["reset"] = () => { + this.clearStoredOriginals(); + this.cancelCatchUp(); + this.hasOutput = false; + return this.originalReset(); + }; + + private readonly clear: XTerm["clear"] = () => { + this.restoreBuffer(); + this.clearStoredOriginals(); + this.cancelCatchUp(); + const result = this.originalClear(); + if (this.compiledPatterns.length > 0) { + this.recolorVisible(); + } + return result; + }; + + private readonly resize: XTerm["resize"] = (cols, rows) => { + this.restoreBuffer(); + const result = this.originalResize(cols, rows); + this.ruleGeneration += 1; + if (this.compiledPatterns.length > 0) { + this.recolorVisible(); + this.markCatchUp(0); + this.scheduleCatchUp(); + } + return result; + }; + + private shouldBypassWrite(data: string | Uint8Array): boolean { + if (this.options.shouldBypassHighlight?.()) return true; + if (typeof data !== "string") return true; + if (shouldDegradeTerminalKeywordHighlight(this.term, data)) return true; + return this.countNewlines(data) >= BULK_WRITE_LINE_BREAKS; + } + + private countNewlines(data: string): number { + let count = 0; + for (let index = 0; index < data.length; index += 1) { + if (data.charCodeAt(index) !== 10) continue; + count += 1; + } + return count; + } + + private rememberScrollPosition(): void { + const buffer = this.term.buffer.active; + this.lastViewportY = buffer.viewportY; + this.lastBaseY = buffer.baseY; + } + + private isOutputDrivenScroll(): boolean { const buffer = this.term.buffer.active; const viewportY = buffer.viewportY; - const rows = this.term.rows; - const cursorY = buffer.cursorY; const baseY = buffer.baseY; - const cursorAbsoluteY = baseY + cursorY; - const overscan = this.getOverscanLines(reason); - const viewportStart = viewportY; - const viewportEnd = viewportY + rows - 1; - const rangeStart = Math.max(0, viewportY - overscan); - const rangeEnd = viewportEnd + overscan; + // Full scrollback keeps baseY/viewportY pinned while rows recycle. That is + // still output-driven and must not rematch the visible area on every write. + const pinnedToBottom = viewportY === baseY; + const followedOutput = pinnedToBottom || ( + baseY !== this.lastBaseY + && viewportY - this.lastViewportY === baseY - this.lastBaseY + ); + this.lastViewportY = viewportY; + this.lastBaseY = baseY; + return followedOutput; + } - this.beginTerminalRefreshTracking(viewportStart, viewportEnd); - let writeContinuationPending = false; + private hasPendingCatchUp(): boolean { + return this.catchUpFrom !== null || this.catchUpStartMarker !== null + || this.catchUpTimer !== null || this.catchUpRunning; + } + + private resolveCatchUpY(): number | null { + if (this.catchUpStartMarker) { + if (!this.catchUpStartMarker.isDisposed) { + return Math.max(0, this.catchUpStartMarker.line); + } + // Trimmed away: the pending range is the whole remaining buffer. + this.catchUpStartMarker = null; + this.catchUpFrom = 0; + return 0; + } + return this.catchUpFrom; + } + + private replaceCatchUpMarker(absoluteY: number | null): void { + this.catchUpStartMarker?.dispose(); + this.catchUpStartMarker = null; + if (absoluteY === null) return; + const buffer = this.term.buffer.active; + if (buffer.type !== "normal") return; + const cursor = buffer.baseY + buffer.cursorY; + this.catchUpStartMarker = this.term.registerMarker(absoluteY - cursor); + } + + private markCatchUp(fromY: number): void { + const current = this.resolveCatchUpY(); + const next = current === null ? fromY : Math.min(current, fromY); + this.catchUpFrom = next; + // Already covers this write. After trim, numeric 0 is enough — do not + // registerMarker on every subsequent flood chunk. + if (current !== null && current <= fromY) return; + this.replaceCatchUpMarker(next); + } + + private scheduleCatchUp(): void { + if (this.disposed || this.resolveCatchUpY() === null) return; + if (!this.resolveCatchUp) { + this.catchUpPromise = new Promise((resolve) => { + this.resolveCatchUp = resolve; + }); + } + const quietMs = XTERM_PERFORMANCE_CONFIG.highlighting.largeOutputQuietMs ?? 480; + this.catchUpDueAt = performance.now() + quietMs; + if (this.catchUpTimer !== null) return; + const arm = (): void => { + const wait = Math.max(1, this.catchUpDueAt - performance.now()); + this.catchUpTimer = setTimeout(() => { + this.catchUpTimer = null; + if (this.disposed) return; + if (performance.now() < this.catchUpDueAt) { + arm(); + return; + } + void this.runCatchUp(); + }, wait); + }; + arm(); + } + + private cancelCatchUp(): void { + if (this.catchUpTimer !== null) clearTimeout(this.catchUpTimer); + this.catchUpTimer = null; + this.catchUpDueAt = 0; + this.catchUpFrom = null; + this.catchUpStartMarker?.dispose(); + this.catchUpStartMarker = null; + this.catchUpCounted = false; + this.catchUpGeneration += 1; + this.resolveCatchUp?.(); + this.resolveCatchUp = null; + } + + private async runCatchUp(): Promise { + if (this.disposed || this.resolveCatchUpY() === null || this.catchUpRunning) return; + const generation = this.catchUpGeneration; + this.catchUpRunning = true; + if (!this.catchUpCounted) { + this.rebuildCount += 1; + this.catchUpCounted = true; + } + const started = performance.now(); + let pausedOnAlternate = false; try { - this.syncLineDecorationIndex(); - const previousRange = this.lastRenderRange; - - if (reason === "write") { - writeContinuationPending = this.processDirtyLinesInRange( - rangeStart, - rangeEnd, - cursorAbsoluteY, - "write", - ); - } else if (reason === "scroll") { - this.processScrollViewport( - viewportStart, - viewportEnd, - cursorAbsoluteY, - previousRange, - ); - } else if (previousRange !== null && this.lineDecorations.size > 0) { - if (rangeStart < previousRange.start) { - this.processLineRange(rangeStart, Math.min(rangeEnd, previousRange.start - 1), cursorAbsoluteY); + let nextY = Math.max(0, this.resolveCatchUpY() ?? 0); + let turnStarted = performance.now(); + while (!this.disposed && generation === this.catchUpGeneration) { + const buffer = this.term.buffer.active; + if (buffer.type !== "normal") { + pausedOnAlternate = true; + break; } - if (rangeEnd > previousRange.end) { - this.processLineRange(Math.max(rangeStart, previousRange.end + 1), rangeEnd, cursorAbsoluteY); + if (nextY >= buffer.length) { + this.catchUpFrom = null; + this.replaceCatchUpMarker(null); + break; } - } else { - this.processLineRange(rangeStart, rangeEnd, cursorAbsoluteY); - } - - if (reason === "write") { - this.pruneWriteDecorationsIfNeeded(rangeStart, rangeEnd, true); - this.finishEnterViewportScan( - writeContinuationPending, - viewportStart, - viewportEnd, - ); - } - - // `write` refresh only processes dirty lines and does NOT guarantee the whole - // viewport/render range is covered. If we still persist these ranges, later - // scroll refreshes may take an incremental path and incorrectly skip lines. - if (reason === "write") { - this.lastViewportRange = null; - this.lastRenderRange = null; - } else if (reason === "scroll") { - // processScrollViewport records the contiguous range already indexed. - } else { - this.lastViewportRange = { start: viewportStart, end: viewportEnd }; - this.lastRenderRange = { start: rangeStart, end: rangeEnd }; - if (reason === "full" && this.enterViewportScanInProgress) { - this.triggerRefresh("debounced", "write"); + const sliceEnd = Math.min(buffer.length - 1, nextY + RECOLOR_SLICE_LINES - 1); + const viewportStart = buffer.viewportY; + const viewportEnd = viewportStart + this.term.rows - 1; + const refresh = sliceEnd >= viewportStart && nextY <= viewportEnd; + this.recolorRange(nextY, sliceEnd, refresh, false); + nextY = sliceEnd + 1; + if (nextY >= buffer.length) { + this.catchUpFrom = null; + this.replaceCatchUpMarker(null); + break; + } + this.catchUpFrom = nextY; + if (performance.now() - turnStarted >= RECOLOR_SLICE_BUDGET_MS) { + this.replaceCatchUpMarker(nextY); + await yieldToRenderer(); + turnStarted = performance.now(); + nextY = Math.max(0, this.resolveCatchUpY() ?? nextY); } } } finally { - this.flushTerminalRefresh(); - } - } - - private finishEnterViewportScan( - continuationPending: boolean, - viewportStart: number, - viewportEnd: number, - ): void { - if (!this.enterViewportScanInProgress || continuationPending) return; - this.enterViewportScanInProgress = false; - if (!this.enterViewportScanNeedsRepeat) return; - - this.enterViewportScanNeedsRepeat = false; - this.addDirtyRange(viewportStart, viewportEnd); - this.enterViewportScanInProgress = true; - this.triggerRefresh("continuation", "write"); - } - - private beginTerminalRefreshTracking(viewportStart: number, viewportEnd: number) { - this.activeRefreshViewport = { start: viewportStart, end: viewportEnd }; - this.pendingTerminalRefreshRange = null; - } - - private markTerminalRefreshNeeded(lineY: number) { - const viewport = this.activeRefreshViewport; - if (!viewport || lineY < viewport.start || lineY > viewport.end) return; - if (!this.pendingTerminalRefreshRange) { - this.pendingTerminalRefreshRange = { start: lineY, end: lineY }; - return; - } - this.pendingTerminalRefreshRange.start = Math.min(this.pendingTerminalRefreshRange.start, lineY); - this.pendingTerminalRefreshRange.end = Math.max(this.pendingTerminalRefreshRange.end, lineY); - } - - private flushTerminalRefresh() { - const viewport = this.activeRefreshViewport; - const refreshRange = this.pendingTerminalRefreshRange; - this.activeRefreshViewport = null; - this.pendingTerminalRefreshRange = null; - if (!viewport || !refreshRange) return; - - const startRow = Math.max(0, refreshRange.start - viewport.start); - const endRow = Math.min(this.term.rows - 1, refreshRange.end - viewport.start); - if (startRow <= endRow) { - this.term.refresh(startRow, endRow); - } - } - - private toIndexedLine(lineY: number): number { - return lineY - this.markerLineOffset; - } - - private getLineDecorationState(lineY: number): LineDecorationState | undefined { - this.syncLineDecorationIndex(); - let state = this.lineDecorations.get(this.toIndexedLine(lineY)); - if (state && state.marker.line !== lineY) { - this.syncLineDecorationIndex(true); - state = this.lineDecorations.get(this.toIndexedLine(lineY)); - } - return state; - } - - private syncLineDecorationIndex(force = false) { - force = force || this.lineDecorationIndexNeedsRebuild; - if (this.lineDecorations.size === 0) { - this.markerLineOffset = 0; - this.lineDecorationIndexNeedsRebuild = false; - return; - } - - if (!force) { - const anchor = this.lineDecorations.values().next().value as LineDecorationState | undefined; - if (anchor && !anchor.marker.isDisposed && anchor.marker.line >= 0) { - this.markerLineOffset += anchor.marker.line - (anchor.indexedLine + this.markerLineOffset); - return; - } - } - - const nextLineDecorations = new Map(); - const staleStates = new Set(); - - for (const state of this.lineDecorations.values()) { - if (state.marker.isDisposed || state.marker.line < 0) { - staleStates.add(state); - continue; - } - state.indexedLine = state.marker.line; - const existing = nextLineDecorations.get(state.indexedLine); - if (existing && existing !== state) { - staleStates.add(existing); - } - nextLineDecorations.set(state.indexedLine, state); - } - - for (const state of nextLineDecorations.values()) { - staleStates.delete(state); - } - - this.lineDecorations = nextLineDecorations; - this.markerLineOffset = 0; - this.lineDecorationIndexNeedsRebuild = false; - if (staleStates.size > 0) { - this.lastRenderRange = null; - } - - for (const state of staleStates) { - const markerLineBeforeDispose = state.marker.isDisposed ? -1 : state.marker.line; - state.decorations.forEach((decoration) => decoration.dispose()); - state.marker.dispose(); - if (markerLineBeforeDispose >= 0) { - this.markTerminalRefreshNeeded(markerLineBeforeDispose); + this.catchUpRunning = false; + this.lastRebuildTimings = { total: performance.now() - started }; + if (this.disposed) { + this.resolveCatchUp?.(); + this.resolveCatchUp = null; + } else if (this.resolveCatchUpY() === null) { + this.catchUpCounted = false; + this.resolveCatchUp?.(); + this.resolveCatchUp = null; + } else if (pausedOnAlternate) { + this.resolveCatchUp?.(); + this.resolveCatchUp = null; + } else if (generation === this.catchUpGeneration) { + this.scheduleCatchUp(); + } else { + void this.runCatchUp(); } } } - private prunePersistentDecorations() { - const config = XTERM_PERFORMANCE_CONFIG.highlighting; - const maxPersistentLines = Math.min( - config.maxPersistentDecorationLines, - Math.max( - config.minPersistentDecorationLines, - this.term.rows * config.persistentDecorationViewports, - ), - ); - - while (this.lineDecorations.size > maxPersistentLines) { - const oldest = this.lineDecorations.values().next().value as LineDecorationState | undefined; - if (!oldest) break; - this.disposeLineDecorations(oldest.marker.line, oldest); - } - } - - private processDirtyLinesInRange( - rangeStart: number, - rangeEnd: number, - cursorAbsoluteY: number, - continuationReason: RefreshReason - ): boolean { - if (this.dirtyAllInRenderRange) { - this.dirtySegments = [{ start: rangeStart, end: rangeEnd }]; - this.rebuildDirtyLineCount(); - this.dirtyAllInRenderRange = false; - } - - if (this.dirtySegments.length === 0) { - return false; - } - - const dirtyInRange: DirtyLineSegment[] = []; - for (const segment of this.dirtySegments) { - if (segment.end < rangeStart) continue; - if (segment.start > rangeEnd) break; - dirtyInRange.push({ - start: Math.max(segment.start, rangeStart), - end: Math.min(segment.end, rangeEnd), - }); - } - - if (dirtyInRange.length === 0) { - return false; - } - - const { writeRefreshBudgetMs, dirtySegmentChunkSize } = this.getAdaptiveHighlightingProfile(); - const segmentChunkSize = Math.max(1, dirtySegmentChunkSize); - const startTime = performance.now(); - - for (const segment of dirtyInRange) { - let chunkStart = segment.start; - while (chunkStart <= segment.end) { - const chunkEnd = Math.min(segment.end, chunkStart + segmentChunkSize - 1); - this.processLineRange(chunkStart, chunkEnd, cursorAbsoluteY); - this.removeDirtyRange(chunkStart, chunkEnd); - chunkStart = chunkEnd + 1; - - if (chunkStart <= segment.end && performance.now() - startTime >= writeRefreshBudgetMs) { - this.triggerRefresh("continuation", continuationReason); - return true; - } - } - if ( - this.dirtySegments.length > 0 - && performance.now() - startTime >= writeRefreshBudgetMs - ) { - this.triggerRefresh("continuation", continuationReason); - return true; - } - } - return false; - } - - private pruneWriteDecorationsIfNeeded( - rangeStart: number, - rangeEnd: number, - deferUntilIdle = false, - ): void { - const renderLineCount = Math.max(1, rangeEnd - rangeStart + 1); - const highWaterMark = Math.max(64, renderLineCount * 2); - if (this.lineDecorations.size <= highWaterMark) return; - if (deferUntilIdle) { - const hardLimit = Math.max(256, highWaterMark * 4); - if (this.lineDecorations.size > hardLimit) { - const trimTarget = Math.max(highWaterMark, Math.floor(hardLimit * 0.75)); - this.pruneWriteDecorationsToLimit(rangeStart, rangeEnd, trimTarget); - } - this.scheduleDeferredWritePrune(); - return; - } - - // Decoration registration/removal makes xterm repaint the full viewport. - // Prune in batches so ordinary one-line output keeps existing highlights - // stable while long-running output remains bounded. - this.syncLineDecorationIndex(); - for (const state of [...this.lineDecorations.values()]) { - const lineY = state.marker.isDisposed ? -1 : state.marker.line; - if (lineY < rangeStart || lineY > rangeEnd || state.marker.isDisposed) { - this.disposeLineDecorations(lineY, state); - } - } - } - - private pruneWriteDecorationsToLimit( - rangeStart: number, - rangeEnd: number, - targetSize: number, - ): void { - this.syncLineDecorationIndex(); - for (const state of [...this.lineDecorations.values()]) { - if (this.lineDecorations.size <= targetSize) return; - const lineY = state.marker.isDisposed ? -1 : state.marker.line; - if (lineY < rangeStart || lineY > rangeEnd || state.marker.isDisposed) { - this.disposeLineDecorations(lineY, state); - } - } - } - - private scheduleDeferredWritePrune(): void { - if (this.writePruneTimer) clearTimeout(this.writePruneTimer); - this.writePruneTimer = setTimeout(() => { - this.writePruneTimer = null; - if (!this.enabled || this.compiledRules.length === 0) return; - const now = performance.now(); - if ( - ( - this.lastUserInputAt > 0 - && now - this.lastUserInputAt < KeywordHighlighter.WRITE_PRUNE_IDLE_MS - ) - || ( - this.lastWriteAt > 0 - && now - this.lastWriteAt < KeywordHighlighter.WRITE_PRUNE_IDLE_MS - ) - ) { - this.scheduleDeferredWritePrune(); - return; - } - const buffer = this.term.buffer.active; - const overscan = this.getOverscanLines("write"); - const rangeStart = Math.max(0, buffer.viewportY - overscan); - const rangeEnd = buffer.viewportY + this.term.rows - 1 + overscan; - this.pruneWriteDecorationsIfNeeded(rangeStart, rangeEnd); - }, KeywordHighlighter.WRITE_PRUNE_IDLE_MS); - } - - private scheduleEnterInputIdleClear(): void { - if (this.enterInputIdleTimer) clearTimeout(this.enterInputIdleTimer); - this.enterInputIdleTimer = setTimeout(() => { - this.enterInputIdleTimer = null; - this.enterInputPending = false; - this.enterSuppressDecorationMutation = false; - this.enterWriteParsedSeen = false; - this.enterSuppressionStartedAt = 0; - // Catch up any viewport motion deferred while Enter protection blocked - // scroll refresh (e.g. user scrolled during the post-Enter window). - this.markVisibleRangeDirty(); - this.triggerRefresh("debounced", "write"); - }, KeywordHighlighter.ENTER_INPUT_GUARD_MS); - } - - /** - * True when follow-up Enter writes look like sustained command output. - * WriteParsed callback count alone cannot prove that — a split prompt may - * need three (or more) batches — so a write burst lifts mute early. - * Slow streams never burst and keep rearming the idle timer; after the - * Enter window, prompt redraw is done and mutation is safe. - */ - private shouldLiftEnterDecorationSuppression(): boolean { - if (!this.enterSuppressDecorationMutation) return false; - const now = performance.now(); - if (this.isWriteBurstActive(now)) return true; - return ( - this.enterSuppressionStartedAt > 0 - && now - this.enterSuppressionStartedAt >= KeywordHighlighter.ENTER_INPUT_GUARD_MS - ); - } - - private isBrowsingScrollback(): boolean { + private recolorVisible(): void { const buffer = this.term.buffer.active; - return buffer.viewportY < buffer.baseY; + if (buffer.type !== "normal") return; + const start = buffer.viewportY; + const end = Math.min(buffer.length - 1, start + this.term.rows - 1); + this.recolorRange(start, end, true, false); } - private hasOutputDrivenViewportChange(): boolean { - return ( - this.hasOutputPositionChangedSinceLastSnapshot() - || this.hasDecorationMarkerShiftSinceLastRefresh() - ); - } - - private mergeRefreshReason(current: RefreshReason, next: RefreshReason): RefreshReason { - // Scroll refresh must outrank write refresh. During rapid wheel scroll with - // concurrent output, choosing "write" can skip viewport line scans and leave - // visible gaps until another scroll/render cycle lands. - const weight: Record = { write: 0, scroll: 1, full: 2 }; - return weight[next] > weight[current] ? next : current; - } - - private readBufferSnapshot({ includeViewportProbe = true }: { includeViewportProbe?: boolean } = {}): BufferSnapshot | null { - const buffer = this.term?.buffer?.active; - if (!buffer) return null; - return { - length: buffer.length, - baseY: buffer.baseY, - viewportY: buffer.viewportY, - cursorAbsoluteY: buffer.baseY + buffer.cursorY, - viewportProbe: includeViewportProbe ? this.buildViewportProbe(buffer, this.term.rows) : [], - }; - } - - private hasOutputPositionChangedSinceLastSnapshot(): boolean { - const previous = this.lastBufferSnapshot; - const current = this.readBufferSnapshot({ includeViewportProbe: false }); - if (!previous || !current) return false; - return ( - current.length !== previous.length - || current.baseY !== previous.baseY - || current.cursorAbsoluteY !== previous.cursorAbsoluteY - ); - } - - private hasDecorationMarkerShiftSinceLastRefresh(): boolean { - for (const state of this.lineDecorations.values()) { - if ( - state.marker.isDisposed - || state.marker.line !== state.indexedLine + this.markerLineOffset - ) { - return true; - } - } - return false; - } - - private buildViewportProbe(buffer: IBuffer, rows: number): readonly ViewportProbeSample[] { - if (rows <= 0) return []; - const viewportStart = buffer.viewportY; - const viewportEnd = viewportStart + rows - 1; - const offsets = [0, 0.125, 0.25, 0.375, 0.5, 0.625, 0.75, 0.875, 1]; - const lineSet = new Set(); - for (const offset of offsets) { - const targetLine = viewportStart + Math.round((rows - 1) * offset); - lineSet.add(Math.max(viewportStart, Math.min(viewportEnd, targetLine))); - } - - const probe: ViewportProbeSample[] = []; - for (const lineY of lineSet) { - const lineText = buffer.getLine(lineY)?.translateToString(true) ?? ""; - probe.push({ lineY, hash: this.hashProbeText(lineText) }); - } - probe.sort((left, right) => left.lineY - right.lineY); - return probe; - } - - private hashProbeText(text: string): number { - const sampleLimit = 512; - let hash = 2166136261; - const maxLen = Math.min(text.length, sampleLimit); - for (let index = 0; index < maxLen; index += 1) { - hash ^= text.charCodeAt(index); - hash = Math.imul(hash, 16777619); - } - hash ^= text.length; - return hash >>> 0; - } - - private collectViewportProbeDiffLines( - currentProbe: readonly ViewportProbeSample[], - previousProbe: readonly ViewportProbeSample[], - ): number[] { - const previousByLine = new Map(previousProbe.map((sample) => [sample.lineY, sample.hash])); - const changedLines: number[] = []; - for (const sample of currentProbe) { - if (previousByLine.get(sample.lineY) !== sample.hash) { - changedLines.push(sample.lineY); - } - } - return changedLines; - } - - private markVisibleRangeDirty() { - this.dirtyAllInRenderRange = true; - this.clearDirtySegments(); - } - - private clearDirtySegments() { - this.dirtySegments = []; - this.dirtyLineCount = 0; - } - - private rebuildDirtyLineCount() { - let total = 0; - for (const segment of this.dirtySegments) { - total += segment.end - segment.start + 1; - } - this.dirtyLineCount = total; - } - - private removeDirtyRange(start: number, end: number) { - if (end < start || this.dirtySegments.length === 0) return; - const next: DirtyLineSegment[] = []; - - for (const segment of this.dirtySegments) { - if (segment.end < start || segment.start > end) { - next.push(segment); - continue; - } - if (segment.start < start) { - next.push({ start: segment.start, end: start - 1 }); - } - if (segment.end > end) { - next.push({ start: end + 1, end: segment.end }); - } - } - - this.dirtySegments = next; - this.rebuildDirtyLineCount(); - } - - private addDirtyRange(start: number, end: number) { - if (this.dirtyAllInRenderRange) return; - if (end < start) return; - const maxDirtyLines = this.getMaxDirtyLines(); - const clampedStart = Math.max(0, start); - const clampedEnd = Math.max(clampedStart, end); - const rangeSize = clampedEnd - clampedStart + 1; - if (rangeSize > maxDirtyLines) { - this.markVisibleRangeDirty(); - return; - } - const merged: DirtyLineSegment[] = []; - let mergeStart = clampedStart; - let mergeEnd = clampedEnd; - let inserted = false; - - for (const segment of this.dirtySegments) { - if (segment.end + 1 < mergeStart) { - merged.push(segment); - continue; - } - if (mergeEnd + 1 < segment.start) { - if (!inserted) { - merged.push({ start: mergeStart, end: mergeEnd }); - inserted = true; - } - merged.push(segment); - continue; - } - mergeStart = Math.min(mergeStart, segment.start); - mergeEnd = Math.max(mergeEnd, segment.end); - } - - if (!inserted) { - merged.push({ start: mergeStart, end: mergeEnd }); - } - - this.dirtySegments = merged; - this.rebuildDirtyLineCount(); - if (this.dirtyLineCount > maxDirtyLines) { - this.markVisibleRangeDirty(); - } - } - - private getMaxDirtyLines(): number { - const rows = Math.max(1, this.term.rows); - const perViewportRow = XTERM_PERFORMANCE_CONFIG.highlighting.dirtyLinesPerViewportRow; - const minDirtyLines = XTERM_PERFORMANCE_CONFIG.highlighting.minDirtyLines; - const maxDirtyLines = XTERM_PERFORMANCE_CONFIG.highlighting.maxDirtyLines; - const dynamicDirtyLines = Math.round(rows * perViewportRow); - return Math.min(maxDirtyLines, Math.max(minDirtyLines, dynamicDirtyLines)); - } - - private markDirtyFromWrite({ includeViewportProbe = true }: { includeViewportProbe?: boolean } = {}) { - this.updateWriteBurst(); - const snapshot = this.readBufferSnapshot({ includeViewportProbe }); - if (!snapshot) { - this.markVisibleRangeDirty(); - return; - } - - if (!this.enabled || this.compiledRules.length === 0) { - this.lastBufferSnapshot = snapshot; - return; - } - - const prev = this.lastBufferSnapshot; - this.lastBufferSnapshot = snapshot; - - if (!prev) { - this.markVisibleRangeDirty(); - return; - } - - if (snapshot.length < prev.length || snapshot.baseY < prev.baseY) { - this.markVisibleRangeDirty(); - return; - } - - const rows = this.term.rows; - const padding = KeywordHighlighter.DIRTY_SCAN_PADDING; - const cursorSpan = Math.abs(snapshot.cursorAbsoluteY - prev.cursorAbsoluteY); - const baseSpan = Math.abs(snapshot.baseY - prev.baseY); - const largeDeltaThreshold = rows * 4; - - if (cursorSpan > largeDeltaThreshold || baseSpan > largeDeltaThreshold) { - this.markVisibleRangeDirty(); - return; - } - - const sameWindow = - snapshot.length === prev.length && - snapshot.baseY === prev.baseY && - snapshot.viewportY === prev.viewportY; - const changedProbeLines = this.collectViewportProbeDiffLines( - snapshot.viewportProbe, - prev.viewportProbe, - ); - const probeDiffCount = changedProbeLines.length; - const cursorStart = Math.min(prev.cursorAbsoluteY, snapshot.cursorAbsoluteY) - padding; - const cursorEnd = Math.max(prev.cursorAbsoluteY, snapshot.cursorAbsoluteY) + padding; - // Detect in-place ANSI redraw chunks (cursor returns near original line while - // multiple viewport regions are actually rewritten). - if (sameWindow && cursorSpan <= Math.max(1, padding * 2) && probeDiffCount >= 2) { - this.lineDecorationIndexNeedsRebuild = true; - this.markVisibleRangeDirty(); - return; - } - // Single-line ANSI redraw via save/restore: also mark the rewritten probe - // line dirty when it is away from the cursor. - if (sameWindow && cursorSpan <= Math.max(1, padding * 2) && probeDiffCount === 1) { - const changedLine = changedProbeLines[0]; - if (changedLine < cursorStart || changedLine > cursorEnd) { - this.addDirtyRange(changedLine - padding, changedLine + padding); - } - } - - this.addDirtyRange(cursorStart, cursorEnd); - - if (snapshot.viewportY !== prev.viewportY) { - const prevViewportEnd = prev.viewportY + rows - 1; - const currViewportEnd = snapshot.viewportY + rows - 1; - if (snapshot.viewportY > prev.viewportY) { - this.addDirtyRange(prevViewportEnd + 1 - padding, currViewportEnd + padding); - } else { - this.addDirtyRange(snapshot.viewportY - padding, prev.viewportY - 1 + padding); - } - } - } - - private decayWriteBurst(now: number) { - if (this.lastBurstDecayAt === 0) { - this.lastBurstDecayAt = now; - return; - } - const elapsed = now - this.lastBurstDecayAt; - if (elapsed < KeywordHighlighter.WRITE_BURST_DECAY_MS) return; - const steps = Math.floor(elapsed / KeywordHighlighter.WRITE_BURST_DECAY_MS); - if (steps <= 0) return; - this.recentWriteBurst = Math.max(0, this.recentWriteBurst - steps); - this.lastBurstDecayAt += steps * KeywordHighlighter.WRITE_BURST_DECAY_MS; - } - - private updateWriteBurst() { - const now = performance.now(); - this.decayWriteBurst(now); - if (this.lastWriteAt === 0) { - this.recentWriteBurst = 1; - this.lastWriteAt = now; - this.lastBurstDecayAt = now; - return; - } - - const interval = now - this.lastWriteAt; - if (interval <= KeywordHighlighter.WRITE_BURST_INTERVAL_MS) { - this.recentWriteBurst = Math.min(64, this.recentWriteBurst + 1); - } else { - this.recentWriteBurst = Math.max(1, this.recentWriteBurst - 1); - } - this.lastWriteAt = now; - this.lastBurstDecayAt = now; - } - - private isWriteBurstActive(now: number): boolean { - this.decayWriteBurst(now); - if (this.recentWriteBurst < KeywordHighlighter.WRITE_BURST_THRESHOLD) { - return false; - } - return now - this.lastWriteAt <= KeywordHighlighter.WRITE_BURST_DECAY_MS * 2; - } - - private getInputProtectionRemainingMs(now: number): number { - if (this.lastUserInputAt <= 0) return 0; - return Math.max(0, KeywordHighlighter.INPUT_QUIET_MS - (now - this.lastUserInputAt)); - } - - private isInputProtectionActive(now: number): boolean { - return this.getInputProtectionRemainingMs(now) > 0; - } - - private getAdaptiveHighlightingProfile(now = performance.now()) { - const config = XTERM_PERFORMANCE_CONFIG.highlighting; - const overscanLines = this.getBaseOverscanLines(); - const pressure = getTerminalOutputPressure(this.term); - const underOutputPressure = pressure.largeOutput || pressure.longLine || pressure.background; - - if (underOutputPressure) { - return { - overscanLines: Math.max(4, Math.round(overscanLines * 0.25)), - writeRefreshBudgetMs: Math.max(1, Math.floor(config.writeRefreshBudgetMs * 0.35)), - dirtySegmentChunkSize: Math.max(8, Math.round(config.dirtySegmentChunkSize * 0.35)), - debounceMs: Math.max( - config.debounceMs, - config.largeOutputDebounceMs ?? KeywordHighlighter.WRITE_BURST_DEBOUNCE_MS, - KeywordHighlighter.WRITE_BURST_DEBOUNCE_MS, - ), - immediateMinIntervalMs: Math.max( - config.immediateMinIntervalMs, - config.largeOutputImmediateMinIntervalMs - ?? KeywordHighlighter.WRITE_BURST_IMMEDIATE_MIN_INTERVAL_MS, - KeywordHighlighter.WRITE_BURST_IMMEDIATE_MIN_INTERVAL_MS, - ), - }; - } - - if (!this.isWriteBurstActive(now)) { - return { - overscanLines, - writeRefreshBudgetMs: config.writeRefreshBudgetMs, - dirtySegmentChunkSize: config.dirtySegmentChunkSize, - debounceMs: config.debounceMs, - immediateMinIntervalMs: config.immediateMinIntervalMs, - }; - } - - return { - overscanLines: Math.max(8, Math.round(overscanLines * KeywordHighlighter.WRITE_BURST_OVERSCAN_SCALE)), - writeRefreshBudgetMs: Math.max(1, config.writeRefreshBudgetMs * KeywordHighlighter.WRITE_BURST_BUDGET_SCALE), - dirtySegmentChunkSize: Math.max(8, Math.round(config.dirtySegmentChunkSize * KeywordHighlighter.WRITE_BURST_CHUNK_SCALE)), - debounceMs: Math.max(config.debounceMs, KeywordHighlighter.WRITE_BURST_DEBOUNCE_MS), - immediateMinIntervalMs: Math.max( - config.immediateMinIntervalMs, - KeywordHighlighter.WRITE_BURST_IMMEDIATE_MIN_INTERVAL_MS - ), - }; - } - - private shouldDeferRefreshForWriteBurst( - mode: "immediate" | "debounced" | "continuation", - reason: RefreshReason, - now: number - ): boolean { - if (mode !== "immediate") return false; - if (!this.isWriteBurstActive(now)) return false; - if (now - this.lastRefreshTime >= KeywordHighlighter.WRITE_BURST_HIGHLIGHT_PAUSE_MS) { - return false; - } - return reason === "write"; - } - - private getOverscanLines(reason: RefreshReason): number { - if (reason === "scroll") { - return 0; - } - if (reason === "write") { - return this.getAdaptiveHighlightingProfile().overscanLines; - } - return this.getBaseOverscanLines(); - } - - private getBaseOverscanLines(): number { - const ratio = XTERM_PERFORMANCE_CONFIG.highlighting.overscanViewportRatio; - return Math.max(1, Math.round(this.term.rows * ratio)); - } - - private getWriteBurstDeferDelay(now: number): number { - const quietWindow = Math.max( - KeywordHighlighter.WRITE_BURST_HIGHLIGHT_PAUSE_MS, - this.getAdaptiveHighlightingProfile(now).debounceMs - ); - if (this.lastWriteAt <= 0) { - return quietWindow; - } - const elapsedSinceWrite = now - this.lastWriteAt; - return Math.max(16, quietWindow - elapsedSinceWrite); - } - - private createWrappedBlockScanCache(): WrappedBlockScanCache { - return { - contexts: new Map(), - cappedMiss: null, - }; - } - - private processLineRange( - start: number, - end: number, - cursorAbsoluteY: number, - wrappedBlockCache = this.createWrappedBlockScanCache(), - ) { - if (end < start) return; + private recolorRange(startY: number, endY: number, refresh: boolean, force: boolean): void { const buffer = this.term.buffer.active; - const pressure = getTerminalOutputPressure(this.term); - // Idle Enter must not mutate prompt-area decorations (xterm full-viewport - // flash). A real scrollback browse still needs new decorations: the scroll - // path records lastRenderRange even when this guard skips apply. - const allowEnterBrowseDecorations = this.enterSuppressDecorationMutation - && this.isBrowsingScrollback(); - for (let lineY = start; lineY <= end; lineY++) { - const line = buffer.getLine(lineY); - if (!line) { - if (!this.enterSuppressDecorationMutation) { - this.disposeLineDecorations(lineY); - } + if (buffer.type !== "normal") return; + const first = Math.max(0, Math.min(startY, endY)); + const last = Math.min(buffer.length - 1, Math.max(startY, endY)); + if (last < first) return; + let y = first; + for (let walked = 0; y > 0 && buffer.getLine(y)?.isWrapped && walked < MAX_LOGICAL_LINE_ROWS; walked += 1) { + y -= 1; + } + let paintedStart = Number.POSITIVE_INFINITY; + let paintedEnd = -1; + while (y <= last) { + const bounds = this.logicalLineBounds(y); + if (!bounds) { + y += 1; continue; } + this.recolorLogicalBounds(bounds.startY, bounds.endY, force); + paintedStart = Math.min(paintedStart, bounds.startY); + paintedEnd = Math.max(paintedEnd, bounds.endY); + y = bounds.endY + 1; + } + if (refresh && paintedEnd >= paintedStart) this.refreshAbsolute(paintedStart, paintedEnd); + } - const lineText = line.translateToString(true); // true = trim right whitespace - if (!lineText) { - if (!this.enterSuppressDecorationMutation) { - this.disposeLineDecorations(lineY); - } + private logicalLineBounds(startY: number): { startY: number; endY: number } | null { + const buffer = this.term.buffer.active; + if (!buffer.getLine(startY)) return null; + let first = startY; + let last = startY; + while ( + last + 1 < buffer.length + && buffer.getLine(last + 1)?.isWrapped + && last - first + 1 < MAX_LOGICAL_LINE_ROWS + ) { + last += 1; + } + return { startY: first, endY: last }; + } + + private readLogicalLineText(startY: number, endY: number): string { + const buffer = this.term.buffer.active; + let text = ""; + for (let y = startY; y <= endY; y += 1) { + text += buffer.getLine(y)?.translateToString(y === endY) ?? ""; + } + return text; + } + + private recolorLogicalBounds(startY: number, endY: number, force: boolean): void { + if (!force && this.logicalLineIsCurrent(startY, endY)) return; + for (let y = startY; y <= endY; y += 1) this.restorePhysicalLine(y); + if (this.compiledPatterns.length === 0) { + this.stampLogicalLine(startY, endY); + return; + } + if (collectMatches(this.readLogicalLineText(startY, endY), this.compiledPatterns).length === 0) { + this.stampLogicalLine(startY, endY); + return; + } + const logical = this.readLogicalLine(startY, endY); + if (!logical) return; + const matches = collectMatches(logical.text, this.compiledPatterns); + for (const match of matches) { + const startCell = logical.cellAtStringOffset[match.start]; + const lastCell = match.end > match.start + ? logical.cellAtStringOffset[match.end - 1] + : startCell; + if (!startCell || !lastCell) continue; + // Exclusive string ends can land mid-grapheme and map to the same cell. + // Color that cell instead of building an empty [x, x) range. + if (startCell.y === lastCell.y) { + this.colorPhysicalRange(startCell.y, startCell.x, lastCell.x + 1, match.rgb); continue; } - - const hasWrappedContext = this.hasWrappedNeighbor(buffer, lineY, line); - const cachedRanges = hasWrappedContext - ? pressure.longLine - ? this.getCachedRanges(line, lineText, false) - : this.scanWrappedLine(buffer, lineY, line, lineText, wrappedBlockCache) - : this.getCachedRanges(line, lineText); - if (cachedRanges.length === 0) { - if (!this.enterSuppressDecorationMutation) { - this.disposeLineDecorations(lineY); - } - continue; + const startLine = this.term.buffer.active.getLine(startCell.y); + this.colorPhysicalRange(startCell.y, startCell.x, startLine?.length ?? startCell.x + 1, match.rgb); + for (let y = startCell.y + 1; y < lastCell.y; y += 1) { + const line = this.term.buffer.active.getLine(y); + if (line) this.colorPhysicalRange(y, 0, line.length, match.rgb); } - - const signature = this.buildRangesSignature(cachedRanges); - const existing = this.getLineDecorationState(lineY); - if ( - existing && - !existing.marker.isDisposed && - existing.decorations.length > 0 && - existing.decorations.every((decoration) => !decoration.isDisposed) && - existing.marker.line === lineY && - existing.signature === signature - ) { - continue; - } - - // Idle Enter: keep prior decorations mounted. Scrollback browse still - // creates decorations on unindexed lines so matches are visible before - // the 600ms guard; lines that already have decorations stay untouched. - if (this.enterSuppressDecorationMutation) { - if (!allowEnterBrowseDecorations) { - continue; - } - if (existing && existing.decorations.length > 0) { - continue; - } - } - - this.disposeLineDecorations(lineY, existing); - this.applyLineDecorations(lineY, cachedRanges, signature, cursorAbsoluteY); + this.colorPhysicalRange(lastCell.y, 0, lastCell.x + 1, match.rgb); } + this.stampLogicalLine(startY, endY); } - private processScrollViewport( - start: number, - end: number, - cursorAbsoluteY: number, - previousRange: DirtyLineSegment | null, - ) { - const wrappedBlockCache = this.createWrappedBlockScanCache(); - const overlapsPreviousRange = previousRange !== null - && start <= previousRange.end + 1 - && end + 1 >= previousRange.start; - - if (!overlapsPreviousRange || previousRange === null) { - this.processLineRange(start, end, cursorAbsoluteY, wrappedBlockCache); - this.lastRenderRange = { start, end }; - this.removeDirtyRange(start, end); - this.dirtyAllInRenderRange = false; - } else { - if (start < previousRange.start) { - const exposedEnd = Math.min(end, previousRange.start - 1); - this.processLineRange( - start, - exposedEnd, - cursorAbsoluteY, - wrappedBlockCache, - ); - this.removeDirtyRange(start, exposedEnd); + private logicalLineIsCurrent(startY: number, endY: number): boolean { + const buffer = this.term.buffer.active; + for (let y = startY; y <= endY; y += 1) { + const publicLine = buffer.getLine(y); + const internal = getInternalLine(publicLine); + if (!internal || this.coloredGeneration.get(internal) !== this.ruleGeneration) { + return false; } - if (end > previousRange.end) { - const exposedStart = Math.max(start, previousRange.end + 1); - this.processLineRange( - exposedStart, - end, - cursorAbsoluteY, - wrappedBlockCache, - ); - this.removeDirtyRange(exposedStart, end); - } - - // Overlap was previously indexed; only rescan lines still marked dirty by - // writes (in-place redraws). Never clear the whole viewport dirty set here — - // scroll can outrank/cancel a pending write refresh. - const overlapStart = Math.max(start, previousRange.start); - const overlapEnd = Math.min(end, previousRange.end); - if ( - overlapStart <= overlapEnd - && (this.dirtyAllInRenderRange || this.dirtySegments.length > 0) - ) { - this.processDirtyLinesInRange( - overlapStart, - overlapEnd, - cursorAbsoluteY, - "write", - ); - } - - this.lastRenderRange = { - start: Math.min(start, previousRange.start), - end: Math.max(end, previousRange.end), - }; + const originals = this.originals.get(internal); + const fingerprint = publicLine?.translateToString(false) ?? ""; + const stamped = originals ? originals.fingerprint : this.fingerprints.get(internal); + // An empty/no-match stamp must not survive when the row is later filled + // or recycled with the same BufferLine identity (yes/log floods). + if (stamped === undefined || stamped !== fingerprint) return false; + if (originals && !this.lineStillHasAppliedHighlights(internal, originals)) return false; } - - this.lastViewportRange = { start, end }; - this.prunePersistentDecorations(); + return true; } - private cancelQueuedRefreshSchedule() { - if (this.animationFrameId !== null) { - cancelAnimationFrame(this.animationFrameId); - this.animationFrameId = null; - } - if (this.debounceTimer) { - clearTimeout(this.debounceTimer); - this.debounceTimer = null; - } - } - - private getCachedRanges( - line: IBufferLine, - lineText: string, - includePlugin = true, - ): CachedDecorationRange[] { - const cacheKey = `${includePlugin ? 'all' : 'host'}\0${lineText}`; - const cached = this.matchCache.get(cacheKey); - if (cached) { - // LRU: move to end - this.matchCache.delete(cacheKey); - this.matchCache.set(cacheKey, cached); - return cached; - } - - const ranges = this.scanLine(line, lineText, includePlugin); - this.matchCache.set(cacheKey, ranges); - - const maxEntries = XTERM_PERFORMANCE_CONFIG.highlighting.cacheEntries; - if (this.matchCache.size > maxEntries) { - const oldestKey = this.matchCache.keys().next().value; - if (oldestKey !== undefined) { - this.matchCache.delete(oldestKey); - } - } - - return ranges; - } - - private hasWrappedNeighbor(buffer: IBuffer, lineY: number, line: IBufferLine): boolean { - if (line.isWrapped) return true; - const nextLine = buffer.getLine(lineY + 1); - return !!nextLine?.isWrapped; - } - - private findWrappedBlockStart(buffer: IBuffer, lineY: number): { startY: number; cappedRange?: DirtyLineSegment } { - let startY = lineY; - let scannedRows = 0; - const maxRows = this.getWrappedContextScanRowLimit(); - while (startY > 0) { - scannedRows += 1; - if (scannedRows > maxRows) { - return { startY: -1, cappedRange: { start: startY, end: lineY } }; - } - const current = buffer.getLine(startY); - if (!current?.isWrapped) break; - startY -= 1; - } - return { startY }; - } - - private getWrappedContextScanRowLimit(): number { - const cols = Math.max(1, this.term.cols || 1); - return Math.max(1, Math.ceil(TERMINAL_AUX_LONG_LINE_SCAN_LIMIT_CHARS / cols) + 1); - } - - private buildWrappedBlockContext(buffer: IBuffer, startY: number): WrappedBlockContext | null { - let logicalLineText = ""; - const segmentBounds = new Map(); - let cursorY = startY; - let scannedRows = 0; - const maxRows = this.getWrappedContextScanRowLimit(); - - while (true) { - scannedRows += 1; - if (scannedRows > maxRows) { - return null; - } - const segment = buffer.getLine(cursorY); - if (!segment) break; - const segmentText = segment.translateToString(true); - const lineStart = logicalLineText.length; - const lineEnd = lineStart + segmentText.length; - if (lineEnd > TERMINAL_AUX_LONG_LINE_SCAN_LIMIT_CHARS) { - return null; - } - segmentBounds.set(cursorY, { lineStart, lineEnd }); - logicalLineText += segmentText; - - const nextLine = buffer.getLine(cursorY + 1); - if (!nextLine?.isWrapped) break; - cursorY += 1; - } - - if (segmentBounds.size === 0) return null; - return { logicalLineText, segmentBounds }; - } - - private getWrappedContext( - buffer: IBuffer, - lineY: number, - line: IBufferLine, - cache: WrappedBlockScanCache, - ): { block: WrappedBlockContext; lineStart: number; lineEnd: number } | null { - if (this.isInCappedWrappedMiss(lineY, line, cache)) { - return null; - } - - const { startY, cappedRange } = this.findWrappedBlockStart(buffer, lineY); - if (startY < 0) { - cache.cappedMiss = cappedRange ?? { start: lineY, end: lineY }; - return null; - } - if (!cache.contexts.has(startY)) { - cache.contexts.set(startY, this.buildWrappedBlockContext(buffer, startY)); - } - const block = cache.contexts.get(startY); - if (!block) return null; - const bounds = block.segmentBounds.get(lineY); - if (!bounds) return null; - return { - block, - lineStart: bounds.lineStart, - lineEnd: bounds.lineEnd, - }; - } - - private isInCappedWrappedMiss( - lineY: number, - line: IBufferLine, - cache: WrappedBlockScanCache, + private lineStillHasAppliedHighlights( + line: InternalBufferLine, + originals: LineOriginals, ): boolean { - const miss = cache.cappedMiss; - if (!miss) return false; - if (lineY >= miss.start && lineY <= miss.end) return true; - if (lineY === miss.end + 1 && line.isWrapped) { - miss.end = lineY; - return true; + for (let x = 0; x < line.length; x += 1) { + if (!originals.mask[x]) continue; + if (line._data[x * CELL_INDICES + CELL_FG] === originals.fg[x]) return false; } - if (lineY > miss.end) { - cache.cappedMiss = null; + return true; + } + + private stampLogicalLine(startY: number, endY: number): void { + const buffer = this.term.buffer.active; + for (let y = startY; y <= endY; y += 1) { + const publicLine = buffer.getLine(y); + const internal = getInternalLine(publicLine); + if (!internal) continue; + this.coloredGeneration.set(internal, this.ruleGeneration); + const fingerprint = publicLine?.translateToString(false) ?? ""; + const originals = this.originals.get(internal); + if (originals) originals.fingerprint = fingerprint; + else this.fingerprints.set(internal, fingerprint); + } + } + + private colorPhysicalRange(y: number, startX: number, endX: number, rgb: number): void { + const internal = getInternalLine(this.term.buffer.active.getLine(y)); + if (!internal || endX <= startX) return; + const originals = this.ensureOriginals(internal); + const last = Math.min(internal.length, endX); + for (let x = Math.max(0, startX); x < last; x += 1) { + const dataIndex = x * CELL_INDICES; + const content = internal._data[dataIndex + CELL_CONTENT]; + const currentFg = internal._data[dataIndex + CELL_FG]; + if (!originals.mask[x] || originals.content[x] !== content) { + originals.fg[x] = currentFg; + originals.content[x] = content; + originals.mask[x] = 1; + } + internal._data[dataIndex + CELL_FG] = withRgbFg(originals.fg[x], rgb); + } + const publicLine = this.term.buffer.active.getLine(y); + if (publicLine) originals.fingerprint = publicLine.translateToString(false); + } + + private restorePhysicalLine(y: number, buffer = this.term.buffer.active): void { + const publicLine = buffer.getLine(y); + const internal = getInternalLine(publicLine); + if (!internal) return; + const originals = this.originals.get(internal); + if (!originals) return; + this.coloredGeneration.delete(internal); + for (let x = 0; x < internal.length; x += 1) { + if (!originals.mask[x]) continue; + const dataIndex = x * CELL_INDICES; + const content = internal._data[dataIndex + CELL_CONTENT]; + if (originals.content[x] !== content) { + originals.mask[x] = 0; + continue; + } + internal._data[dataIndex + CELL_FG] = originals.fg[x]; + originals.mask[x] = 0; + } + } + + private restoreBuffer(): void { + const buffer = this.term.buffer.normal; + for (let y = 0; y < buffer.length; y += 1) this.restorePhysicalLine(y, buffer); + } + + private ensureOriginals(line: InternalBufferLine): LineOriginals { + let originals = this.originals.get(line); + if (!originals || originals.fg.length < line.length) { + originals = { + fg: new Uint32Array(line.length), + content: new Uint32Array(line.length), + mask: new Uint8Array(line.length), + fingerprint: this.fingerprints.get(line) ?? originals?.fingerprint ?? "", + }; + this.originals.set(line, originals); + this.fingerprints.delete(line); + } + return originals; + } + + private hasStoredOriginalsInRange(startY: number, endY: number): boolean { + const buffer = this.term.buffer.active; + const last = Math.min(buffer.length - 1, Math.max(startY, endY)); + for (let y = Math.max(0, Math.min(startY, endY)); y <= last; y += 1) { + const internal = getInternalLine(buffer.getLine(y)); + if (internal && this.originals.get(internal)) return true; } return false; } - private scanWrappedLine( - buffer: IBuffer, - lineY: number, - line: IBufferLine, - lineText: string, - wrappedBlockCache: WrappedBlockScanCache, - ): CachedDecorationRange[] { - const context = this.getWrappedContext(buffer, lineY, line, wrappedBlockCache); - if (!context) { - return this.scanLine(line, lineText, false); - } - if (context.block.logicalLineText === lineText) { - return this.scanLine(line, lineText); - } - - const asciiOnly = RE_ASCII_ONLY.test(lineText); - let cellMap: number[] | null = null; - let ranges: CachedDecorationRange[] | null = null; - - context.block.matchRanges ??= this.scanLogicalLineText(context.block.logicalLineText); - for (const { start: matchStart, length: matchLength, color, priority } of context.block.matchRanges) { - const matchEnd = matchStart + matchLength; - if (matchEnd <= context.lineStart || matchStart >= context.lineEnd) { - continue; + private clearStoredOriginals(): void { + const buffer = this.term.buffer.normal; + for (let y = 0; y < buffer.length; y += 1) { + const internal = getInternalLine(buffer.getLine(y)); + if (internal) { + this.originals.delete(internal); + this.fingerprints.delete(internal); } - - const localStart = Math.max(matchStart, context.lineStart) - context.lineStart; - const localEnd = Math.min(matchEnd, context.lineEnd) - context.lineStart; - if (localEnd <= localStart) continue; - - let cellStartCol: number; - let cellEndCol: number; - - if (asciiOnly) { - cellStartCol = localStart; - cellEndCol = localEnd; - } else { - if (cellMap === null) { - cellMap = this.buildStringToCellMap(line); - } - cellStartCol = cellMap[localStart] ?? localStart; - cellEndCol = localEnd < cellMap.length - ? (cellMap[localEnd] ?? localEnd) - : (cellMap[cellMap.length - 1] ?? localEnd); - } - - const cellWidth = cellEndCol - cellStartCol; - if (cellWidth <= 0) continue; - - if (ranges === null) { - ranges = []; - } - ranges.push({ - x: cellStartCol, - width: cellWidth, - color, - priority, - }); } - - if (!ranges || ranges.length === 0) { - return EMPTY_RANGES as CachedDecorationRange[]; - } - if (ranges.length === 1) { - return ranges; - } - return this.mergeDecorationRanges(ranges); } - private scanLogicalLineText(lineText: string): readonly LogicalDecorationRange[] { - const ranges: LogicalDecorationRange[] = []; - let pluginMatchCount = 0; - for (const { forEachMatch, color, priority, plugin } of this.compiledRules) { - if (plugin && pluginMatchCount >= MAX_PLUGIN_DECORATION_MATCHES_PER_LOGICAL_LINE) continue; - forEachMatch(lineText, (start, length) => { - ranges.push({ start, length, color, priority }); - if (plugin) { - pluginMatchCount += 1; - return pluginMatchCount < MAX_PLUGIN_DECORATION_MATCHES_PER_LOGICAL_LINE; - } - }); - } - return ranges; - } - - private scanLine( - line: IBufferLine, - lineText: string, - includePlugin = true, - ): CachedDecorationRange[] { - // ASCII-only lines have a 1:1 string-index-to-cell-column mapping, - // so we can skip the expensive buildStringToCellMap call entirely. - const asciiOnly = RE_ASCII_ONLY.test(lineText); - let cellMap: number[] | null = null; - let ranges: CachedDecorationRange[] | null = null; - let pluginMatchCount = 0; - - // Process each pre-compiled rule - for (const { forEachMatch, color, priority, plugin } of this.compiledRules) { - if (plugin && !includePlugin) continue; - if (plugin && pluginMatchCount >= MAX_PLUGIN_DECORATION_MATCHES_PER_LOGICAL_LINE) continue; - forEachMatch(lineText, (strStart, matchLength) => { - const shouldContinuePluginMatching = !plugin - || ++pluginMatchCount < MAX_PLUGIN_DECORATION_MATCHES_PER_LOGICAL_LINE; - const strEnd = strStart + matchLength; - - let cellStartCol: number; - let cellEndCol: number; - - if (asciiOnly) { - cellStartCol = strStart; - cellEndCol = strEnd; - } else { - // Lazily build cellMap only when a match is found - if (cellMap === null) { - cellMap = this.buildStringToCellMap(line); - } - cellStartCol = cellMap[strStart] ?? strStart; - cellEndCol = strEnd < cellMap.length - ? (cellMap[strEnd] ?? strEnd) - : (cellMap[cellMap.length - 1] ?? strEnd); - } - - const cellWidth = cellEndCol - cellStartCol; - - // Skip if width is 0 or negative (shouldn't happen, but be safe) - if (cellWidth <= 0) return shouldContinuePluginMatching; - - if (ranges === null) { - ranges = []; - } - ranges.push({ - x: cellStartCol, - width: cellWidth, - color, - priority, - }); - return shouldContinuePluginMatching; - }); - } - - if (!ranges || ranges.length === 0) { - return EMPTY_RANGES as CachedDecorationRange[]; - } - if (ranges.length === 1) { - return ranges; - } - return this.mergeDecorationRanges(ranges); - } - - private mergeDecorationRanges(ranges: CachedDecorationRange[]): CachedDecorationRange[] { - // Preserve rule priority (lower index first), and only merge ranges - // within the same priority/color layer. - ranges.sort((a, b) => a.priority - b.priority || a.x - b.x); - const merged: CachedDecorationRange[] = [ranges[0]]; - - for (let index = 1; index < ranges.length; index += 1) { - const current = ranges[index]; - const previous = merged[merged.length - 1]; - if ( - current.priority === previous.priority && - current.color === previous.color && - current.x >= previous.x && - current.x <= previous.x + previous.width - ) { - const mergedEnd = Math.max(previous.x + previous.width, current.x + current.width); - previous.width = mergedEnd - previous.x; - } else { - merged.push(current); + private readLogicalLine(startY: number, endY = startY): LogicalLine | null { + const buffer = this.term.buffer.active; + if (!buffer.getLine(startY)) return null; + const first = startY; + const last = endY; + let text = ""; + const cellAtStringOffset: Array<{ y: number; x: number }> = []; + for (let y = first; y <= last; y += 1) { + const line = buffer.getLine(y); + if (!line) continue; + const mapped = readPluginTerminalBufferText(line, y === last); + const base = text.length; + text += mapped.text; + for (let offset = 0; offset < mapped.text.length; offset += 1) { + cellAtStringOffset[base + offset] = { y, x: mapped.cellAtStringOffset[offset] ?? offset }; } + cellAtStringOffset[text.length] = { + y, + x: mapped.cellAtStringOffset[mapped.text.length] ?? line.length, + }; } + return { startY: first, endY: last, text, cellAtStringOffset }; + } - return merged; + private refreshAbsolute(startY: number, endY: number): void { + const viewportY = this.term.buffer.active.viewportY; + const startRow = Math.max(0, startY - viewportY); + const endRow = Math.min(this.term.rows - 1, endY - viewportY); + if (startRow <= endRow) this.term.refresh(startRow, endRow); } } diff --git a/components/terminal/pluginTerminalVisualProviderHost.test.ts b/components/terminal/pluginTerminalVisualProviderHost.test.ts index 939388249..7b784d251 100644 --- a/components/terminal/pluginTerminalVisualProviderHost.test.ts +++ b/components/terminal/pluginTerminalVisualProviderHost.test.ts @@ -211,6 +211,68 @@ test('visual Provider host preserves semantics when command completion wins the host.dispose(); }); +test('visual Provider host restores annotations after terminal history is rebuilt', async () => { + const markers: Array<{ line: number; isDisposed: boolean; dispose(): void }> = []; + const renderedText: string[] = []; + const term = { + element: null, + buffer: { active: { type: 'normal', baseY: 4, cursorY: 2, cursorX: 0, getLine() { return undefined; } } }, + onWriteParsed() { return { dispose() {} }; }, + registerMarker(offset: number) { + const marker = { + line: 6 + offset, + isDisposed: false, + dispose() { this.isDisposed = true; this.line = -1; }, + }; + markers.push(marker); + return marker; + }, + registerDecoration() { + return { + dispose() {}, + onRender(listener: (element: Record) => void) { + const element = { + className: '', + textContent: '', + title: '', + style: {}, + setAttribute() {}, + }; + listener(element); + renderedText.push(String(element.textContent)); + return { dispose() {} }; + }, + }; + }, + }; + const host = new PluginTerminalVisualProviderHost({ + term: term as never, + isProviderAvailable: (kind) => kind === 'terminal.semantic', + async request() { + return { + stale: false, + results: [{ providerId: 'semantic', status: 'ok', result: { + classification: 'success', + annotations: [{ text: 'retained annotation' }], + } }], + }; + }, + }); + + await host.commandSubmitted('true'); + await host.commandCompleted(); + assert.deepEqual(renderedText, ['success | retained annotation']); + markers[0].dispose(); + + host.terminalRebuilt(); + assert.deepEqual(renderedText, [ + 'success | retained annotation', + 'success | retained annotation', + ]); + assert.equal(markers[1].line, 6); + host.dispose(); +}); + test('visual Provider host preserves semantic queue order at its bounded capacity', async () => { let requests = 0; const renderedText: string[] = []; diff --git a/components/terminal/pluginTerminalVisualProviderHost.ts b/components/terminal/pluginTerminalVisualProviderHost.ts index 7c399f505..908db312c 100644 --- a/components/terminal/pluginTerminalVisualProviderHost.ts +++ b/components/terminal/pluginTerminalVisualProviderHost.ts @@ -134,6 +134,9 @@ export class PluginTerminalVisualProviderHost implements IDisposable { readonly #disposables: IDisposable[] = []; readonly #matcherDecorations: Array = []; readonly #annotationDecorations: Array = []; + #visibleAnnotations: readonly PluginTerminalAnnotation[] = Object.freeze([]); + #annotationAnchorLine: number | null = null; + #annotationMarker: IMarker | null = null; readonly #requestControllers = new Set(); readonly #matcherRequestControllers = new Set(); #matcherTimer: ReturnType | undefined; @@ -196,6 +199,9 @@ export class PluginTerminalVisualProviderHost implements IDisposable { } this.#isProviderAvailable = options.isProviderAvailable ?? (() => true); this.#disposables.push(this.#term.onWriteParsed(() => { + if (this.#annotationMarker && !this.#annotationMarker.isDisposed) { + this.#annotationAnchorLine = this.#annotationMarker.line; + } this.#matcherGeneration += 1; for (const controller of this.#matcherRequestControllers) controller.abort(); this.#matcherRequestControllers.clear(); @@ -432,11 +438,23 @@ export class PluginTerminalVisualProviderHost implements IDisposable { } } - #renderAnnotations(annotations: readonly PluginTerminalAnnotation[]): void { + #renderAnnotations( + annotations: readonly PluginTerminalAnnotation[], + anchorLine?: number | null, + ): void { disposeAll(this.#annotationDecorations); - if (annotations.length === 0 || this.#disposed || !this.#active || !this.#visible) return; - const marker = this.#term.registerMarker(0); + this.#annotationMarker = null; + this.#visibleAnnotations = Object.freeze([...annotations]); + if (annotations.length === 0 || this.#disposed || !this.#active || !this.#visible) { + this.#annotationAnchorLine = null; + return; + } + const buffer = this.#term.buffer.active; + const cursorLine = buffer.baseY + buffer.cursorY; + const marker = this.#term.registerMarker((anchorLine ?? cursorLine) - cursorLine); if (!marker) return; + this.#annotationMarker = marker; + this.#annotationAnchorLine = marker.line; const decoration = this.#term.registerDecoration({ marker, anchor: 'right', x: 0, width: 1, layer: 'top' }); const text = annotations.map((annotation) => annotation.text).join(' | ').slice(0, 512); const description = annotations.map((annotation) => annotation.description).filter(Boolean).join('\n'); @@ -454,6 +472,19 @@ export class PluginTerminalVisualProviderHost implements IDisposable { this.#annotationDecorations.push(decoration, marker); } + /** Recreate markers disposed by a terminal history replay without re-querying plugins. */ + terminalRebuilt(): void { + if (this.#visibleAnnotations.length === 0) return; + this.#renderAnnotations(this.#visibleAnnotations, this.#annotationAnchorLine); + } + + #clearAnnotations(): void { + disposeAll(this.#annotationDecorations); + this.#annotationMarker = null; + this.#visibleAnnotations = Object.freeze([]); + this.#annotationAnchorLine = null; + } + setActive(active: boolean, terminalBackground?: string): void { if (this.#disposed || this.#active === active) { if (active && terminalBackground) void this.refreshBackground('theme-changed', terminalBackground); @@ -475,7 +506,7 @@ export class PluginTerminalVisualProviderHost implements IDisposable { this.#backgroundGeneration += 1; this.#pendingSemantics.splice(0); disposeAll(this.#matcherDecorations); - disposeAll(this.#annotationDecorations); + this.#clearAnnotations(); this.#renderBackground([]); } @@ -493,7 +524,7 @@ export class PluginTerminalVisualProviderHost implements IDisposable { this.#pendingSemantics.splice(0); if (!visible) { disposeAll(this.#matcherDecorations); - disposeAll(this.#annotationDecorations); + this.#clearAnnotations(); this.#renderBackground([]); } if (visible && this.#active) { @@ -510,7 +541,7 @@ export class PluginTerminalVisualProviderHost implements IDisposable { this.#backgroundGeneration += 1; this.#abortProviderRequests(); this.#pendingSemantics.splice(0); - disposeAll(this.#annotationDecorations); + this.#clearAnnotations(); if (!this.#isProviderAvailable('terminal.background')) this.#renderBackground([]); if (!this.#isProviderAvailable('terminal.matcher')) disposeAll(this.#matcherDecorations); if (this.#active && this.#visible) { @@ -557,7 +588,7 @@ export class PluginTerminalVisualProviderHost implements IDisposable { this.#abortProviderRequests(); this.#pendingSemantics.splice(0); disposeAll(this.#matcherDecorations); - disposeAll(this.#annotationDecorations); + this.#clearAnnotations(); this.#backgroundOverlay?.remove(); this.#backgroundOverlay = null; disposeAll(this.#disposables); diff --git a/components/terminal/runtime/createTerminalSessionStarters.ts b/components/terminal/runtime/createTerminalSessionStarters.ts index 48eb59d06..a44155a01 100644 --- a/components/terminal/runtime/createTerminalSessionStarters.ts +++ b/components/terminal/runtime/createTerminalSessionStarters.ts @@ -1797,7 +1797,7 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex { replayBacklog: true }, ); - ctx.disposeExitRef.current = ctx.terminalBackend.onSessionExit(id, (evt) => { + ctx.disposeExitRef.current = ctx.terminalBackend.onSessionExit(id, async (evt) => { ctx.updateStatus("disconnected"); const exitMessage = `\r\n[session closed${evt?.exitCode !== undefined ? ` (code ${evt.exitCode})` : ""}]`; writeTerminalLine(ctx, term, exitMessage); @@ -1810,6 +1810,7 @@ export const createTerminalSessionStarters = (ctx: TerminalSessionStartersContex if (ctx.onTerminalDataCapture && ctx.serializeAddonRef.current) { try { + await ctx.prepareKeywordHighlightSerialization?.(); const terminalData = ctx.serializeAddonRef.current.serialize(); logger.info("[Terminal] Serialized terminal data", { sessionId: ctx.sessionId, diff --git a/components/terminal/runtime/createTerminalSessionStarters.types.ts b/components/terminal/runtime/createTerminalSessionStarters.types.ts index 02213bb1a..88f7a3661 100644 --- a/components/terminal/runtime/createTerminalSessionStarters.types.ts +++ b/components/terminal/runtime/createTerminalSessionStarters.types.ts @@ -209,6 +209,7 @@ export type TerminalSessionStartersContext = { disposeTelnetEchoModeRef?: RefObject<(() => void) | null>; fitAddonRef: RefObject; serializeAddonRef: RefObject; + prepareKeywordHighlightSerialization?: () => Promise; pendingAuthRef: RefObject; promptLineBreakStateRef?: RefObject; sudoAutofillRef?: RefObject; diff --git a/components/terminal/runtime/createXTermRuntime.ts b/components/terminal/runtime/createXTermRuntime.ts index c761e6bfd..f4d829f3e 100644 --- a/components/terminal/runtime/createXTermRuntime.ts +++ b/components/terminal/runtime/createXTermRuntime.ts @@ -536,7 +536,7 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime cursorStyle, cursorBlink, scrollback, - // Decorations (keyword highlighting) use proposed APIs; enable globally so toggles work at runtime. + // Cursor-line rendering and Unicode width handling use proposed APIs. allowProposedApi: true, drawBoldTextInBrightColors, minimumContrastRatio, @@ -2218,7 +2218,9 @@ export const createXTermRuntime = (ctx: CreateXTermRuntimeContext): XTermRuntime resizeScheduler.schedule({ sessionId: id, cols, rows }); }); - const keywordHighlighter = new KeywordHighlighter(term); + const keywordHighlighter = new KeywordHighlighter(term, { + serializeAddon, + }); keywordHighlighter.setRules(keywordHighlightRules, keywordHighlightEnabled); const cursorLineHighlighter = new CursorLineHighlighter(term); diff --git a/components/terminal/runtime/cursorLineHighlight.test.ts b/components/terminal/runtime/cursorLineHighlight.test.ts index c4eeb584f..575165b11 100644 --- a/components/terminal/runtime/cursorLineHighlight.test.ts +++ b/components/terminal/runtime/cursorLineHighlight.test.ts @@ -260,7 +260,7 @@ test('CursorLineHighlighter refreshes after hidden writes become visible', () => highlighter.dispose(); }); -test('CursorLineHighlighter keeps a continuous background under keyword decorations', () => { +test('CursorLineHighlighter keeps a continuous background under colored keyword text', () => { const term = createFakeTerm(10); const keywordMarker = term.registerMarker(0); term.registerDecoration({ @@ -352,7 +352,7 @@ test('CursorLineHighlighter fills a wrap-pending final cell', () => { highlighter.dispose(); }); -test('CursorLineHighlighter leaves colored and inverse cells untouched', () => { +test('CursorLineHighlighter keeps foreground colors and leaves inverse cells untouched', () => { const term = createFakeTerm(10); term.setColoredForegrounds([2, 3]); term.setInverseCells([7]); @@ -363,8 +363,7 @@ test('CursorLineHighlighter leaves colored and inverse cells untouched', () => { assert.deepEqual( term.decorations.map(({ options }) => ({ x: options.x, width: options.width })), [ - { x: 0, width: 2 }, - { x: 4, width: 3 }, + { x: 0, width: 7 }, { x: 8, width: 2 }, ], ); diff --git a/components/terminal/runtime/cursorLineHighlight.ts b/components/terminal/runtime/cursorLineHighlight.ts index 1fdf2bd4a..dbfcf0df1 100644 --- a/components/terminal/runtime/cursorLineHighlight.ts +++ b/components/terminal/runtime/cursorLineHighlight.ts @@ -23,8 +23,8 @@ type HighlightRange = { x: number; width: number }; /** * Highlights the buffer row under the cursor without tinting its glyphs. - * ANSI-colored cells keep their own background; only default-background cells - * receive the opaque theme color. + * Explicit ANSI backgrounds remain untouched. Foreground-only colors still + * receive the opaque theme background so colored text does not leave holes. */ export class CursorLineHighlighter implements IDisposable { private enabled = false; @@ -211,9 +211,7 @@ export class CursorLineHighlighter implements IDisposable { } const isHighlightable = currentCell === undefined || - (currentCell.isBgDefault() && - currentCell.isFgDefault() && - !currentCell.isInverse()); + (currentCell.isBgDefault() && !currentCell.isInverse()); if (isHighlightable && rangeStart === null) rangeStart = x; if ((!isHighlightable || x === cols - 1) && rangeStart !== null) { const end = isHighlightable && x === cols - 1 ? x + 1 : x; diff --git a/components/terminal/runtime/terminalCloseCapture.ts b/components/terminal/runtime/terminalCloseCapture.ts index 25593e6b0..b664fe309 100644 --- a/components/terminal/runtime/terminalCloseCapture.ts +++ b/components/terminal/runtime/terminalCloseCapture.ts @@ -49,7 +49,7 @@ export function resolveHibernateSnapshotCapturePayload( export async function serializeTerminalCloseFallback( term: XTerm, serializeAddon: SerializeAddon, - options: { preferWasm?: boolean } = {}, + options: { preferWasm?: boolean; prepare?: () => Promise } = {}, ): Promise { const snapshot = await serializeTerminalForHibernate(term, serializeAddon, options); return resolveHibernateSnapshotCapturePayload(snapshot); diff --git a/components/terminal/runtime/terminalLineTimestamps.ts b/components/terminal/runtime/terminalLineTimestamps.ts index 8cc9195ef..4c4aefa31 100644 --- a/components/terminal/runtime/terminalLineTimestamps.ts +++ b/components/terminal/runtime/terminalLineTimestamps.ts @@ -792,6 +792,40 @@ const attachLedgerAnchors = ( } }; +/** Reattach sparse anchors after a display-only terminal buffer rebuild. */ +export const restoreTerminalLineTimestampAnchors = (term: XTerm): void => { + const store = getTimestampStore(term); + for (const entry of store.ledger) { + if (!entry.marker?.isDisposed) continue; + entry.marker = undefined; + } + attachLedgerAnchors(term, store, store.ledger); + store.lastSeenBaseY = term.buffer.normal.baseY; + store.lastSeenBufferLength = term.buffer.normal.length; + store.lastSeenCols = _getTerminalColumnCount(term); + notifyTimestampStore(store); +}; + +export const snapshotTerminalLineTimestampLedger = (term: XTerm): Array<{ + label: string; + secondKey: number; + line: number; +}> => getTimestampStore(term).ledger.map((entry) => ({ + label: entry.label, + secondKey: entry.secondKey, + line: entry.marker && !entry.marker.isDisposed ? entry.marker.line : entry.line, +})); + +export const restoreTerminalLineTimestampLedger = ( + term: XTerm, + snapshot: readonly { label: string; secondKey: number; line: number }[], +): void => { + const store = getTimestampStore(term); + store.ledger = snapshot.map((entry) => ({ ...entry })); + store.lastStampSecondKey = store.ledger.at(-1)?.secondKey ?? null; + restoreTerminalLineTimestampAnchors(term); +}; + /** * Refresh ledger.line from live sparse anchors. Drops entries whose markers * were disposed by scrollback trim. Bare (unanchored) lines keep their values diff --git a/components/terminal/runtime/terminalOutputPressure.test.ts b/components/terminal/runtime/terminalOutputPressure.test.ts index f60e57c0d..6df8052cc 100644 --- a/components/terminal/runtime/terminalOutputPressure.test.ts +++ b/components/terminal/runtime/terminalOutputPressure.test.ts @@ -10,6 +10,7 @@ import { resetTerminalOutputPressure, setTerminalOutputPressureVisibility, shouldDegradeTerminalSideWork, + shouldDegradeTerminalKeywordHighlight, shouldSkipTerminalLineTimestamps, } from "./terminalOutputPressure.ts"; import { TERMINAL_LONG_LINE_PRESSURE_BYTES } from "./terminalFlowConstants.ts"; @@ -172,6 +173,21 @@ test("arms large-output early on multi-line writes when scrollback is saturated" } }); +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, @@ -196,6 +212,10 @@ test("saturated multi-line degrades side work but keeps line timestamps", () => // 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); diff --git a/components/terminal/runtime/terminalOutputPressure.ts b/components/terminal/runtime/terminalOutputPressure.ts index 0ffc23f81..9f5edfc08 100644 --- a/components/terminal/runtime/terminalOutputPressure.ts +++ b/components/terminal/runtime/terminalOutputPressure.ts @@ -299,6 +299,19 @@ export const shouldDegradeTerminalSideWork = (term: XTerm): boolean => { return pressure.largeOutput || pressure.longLine; }; +/** + * Keyword coloring only examines the current write, so a stale quiet-window + * bulk flag must not make a later one-line prompt schedule a history rebuild. + */ +export const shouldDegradeTerminalKeywordHighlight = ( + term: XTerm, + data: string, +): boolean => { + const state = getOrCreateState(term); + if (state.longLine || data.length >= TERMINAL_LONG_LINE_PRESSURE_BYTES) return true; + return state.recentSampleBytes >= LARGE_OUTPUT_RATE_BYTES; +}; + /** * Whether line-timestamp registerMarker work should be skipped. * diff --git a/components/terminal/runtime/terminalSessionAttachment.test.ts b/components/terminal/runtime/terminalSessionAttachment.test.ts index 945f7147c..db26cf036 100644 --- a/components/terminal/runtime/terminalSessionAttachment.test.ts +++ b/components/terminal/runtime/terminalSessionAttachment.test.ts @@ -2089,7 +2089,7 @@ test("attachSessionToTerminal clears the backend id before reporting exit", () = assert.equal(sessionIdSeenByConsumer, null); }); -test("attachSessionToTerminal drains hidden final output before exit capture", () => { +test("attachSessionToTerminal drains hidden final output before exit capture", async () => { const { term, writes } = createFakeTerm(); let onData: ((data: string) => void) | null = null; let onExit: ((evt: { reason?: string }) => void) | null = null; @@ -2130,6 +2130,7 @@ test("attachSessionToTerminal drains hidden final output before exit capture", ( assert.deepEqual(writes, []); onExit?.({ reason: "closed" }); + await new Promise((resolve) => setTimeout(resolve, 0)); const expected = "final output\r\n\r\n[session closed]\r\n"; assert.equal(writes.join(""), expected); diff --git a/components/terminal/runtime/terminalSessionAttachment.ts b/components/terminal/runtime/terminalSessionAttachment.ts index 984a2ddb4..d6eb69431 100644 --- a/components/terminal/runtime/terminalSessionAttachment.ts +++ b/components/terminal/runtime/terminalSessionAttachment.ts @@ -956,7 +956,7 @@ export const attachSessionToTerminal = ( ); ctx.terminalBackend.notifyTerminalSessionDisplayReady?.(id); - ctx.disposeExitRef.current = ctx.terminalBackend.onSessionExit(id, (evt) => { + ctx.disposeExitRef.current = ctx.terminalBackend.onSessionExit(id, async (evt) => { // The backend is already gone. In particular, an observe popup must not // run its normal pause/snapshot/restore handoff while closing afterward. if (ctx.sessionRef.current === id) { @@ -971,6 +971,7 @@ export const attachSessionToTerminal = ( if (ctx.onTerminalDataCapture && ctx.serializeAddonRef.current) { try { + await ctx.prepareKeywordHighlightSerialization?.(); const terminalData = ctx.serializeAddonRef.current.serialize(); ctx.onTerminalDataCapture(ctx.sessionId, terminalData); } catch (err) { diff --git a/components/terminal/runtime/terminalWriteCoalescer.test.ts b/components/terminal/runtime/terminalWriteCoalescer.test.ts index 0d170850c..d6607c178 100644 --- a/components/terminal/runtime/terminalWriteCoalescer.test.ts +++ b/components/terminal/runtime/terminalWriteCoalescer.test.ts @@ -899,8 +899,7 @@ test("leave-alt CSI clears latch even while buffer still reports alternate", () // Buffer flips to normal after leave is written; latch must be gone. (term.buffer.active as { type: string }).type = "normal"; enqueueCoalescedTerminalWrite(term, "shell after tui", () => {}); - assert.equal(microtasks.length, 1); - assert.equal(frames.length, 0); + assert.equal(frames.length, 0, "must not stay on rAF after leave-alt"); } finally { resetTerminalWriteCoalescer(term); globalThis.queueMicrotask = originalMicrotask; @@ -956,8 +955,7 @@ test("enter-then-leave in one chunk does not latch rAF forever", () => { microtasks.length = 0; enqueueCoalescedTerminalWrite(term, "ordinary shell output", () => {}); - assert.equal(microtasks.length, 1); - assert.equal(frames.length, 0); + assert.equal(frames.length, 0, "must not latch rAF after enter-then-leave"); } finally { resetTerminalWriteCoalescer(term); globalThis.queueMicrotask = originalMicrotask; diff --git a/components/terminal/runtime/terminalWriteCoalescer.ts b/components/terminal/runtime/terminalWriteCoalescer.ts index c71be7b2d..a342fe3a4 100644 --- a/components/terminal/runtime/terminalWriteCoalescer.ts +++ b/components/terminal/runtime/terminalWriteCoalescer.ts @@ -670,11 +670,11 @@ export const enqueueCoalescedTerminalWrite = ( }, { getMaxPendingBytes: () => resolveCoalescerByteCap(term), shouldFlushScheduledFrame: () => terminalWriteCoalescerFlushGates.get(term)?.() ?? true, - // Tabby streams normal-screen output without waiting for vsync. Keep rAF - // for alternate-screen TUIs (including the enter-alt burst before xterm - // has switched buffer.active.type) so multi-chunk repaints stay atomic. - // When rAF is unavailable (Node unit tests), prefer the "raf" mode so the - // coalescer falls back to an immediate flush (legacy test contract). + // Keep rAF for alternate-screen TUIs (including the enter-alt burst + // before xterm has switched buffer.active.type) so multi-chunk + // repaints stay atomic. Normal-screen output uses Electerm-style burst + // coalescing. When rAF is unavailable (Node unit tests), prefer "raf" + // so the coalescer falls back to an immediate flush (legacy contract). resolveScheduleMode: ({ nextChunk }): WriteCoalesceScheduleMode => { const preapplied = preappliedAltScreenNeedsRafByTerm.get(term); if (preapplied !== undefined) { @@ -693,7 +693,9 @@ export const enqueueCoalescedTerminalWrite = ( const canUseMicrotask = typeof queueMicrotask === "function" && typeof globalThis.requestAnimationFrame === "function"; if (canUseMicrotask) { - return "microtask"; + // Electerm-style 16ms merge after a recent flush; idle echo still + // uses a microtask so typing does not wait a frame. + return "burst"; } return "raf"; }, diff --git a/components/terminal/runtime/writeCoalescer.test.ts b/components/terminal/runtime/writeCoalescer.test.ts index 58fa3cd2d..abf6f421a 100644 --- a/components/terminal/runtime/writeCoalescer.test.ts +++ b/components/terminal/runtime/writeCoalescer.test.ts @@ -4,6 +4,7 @@ import { beforeEach, test } from "node:test"; import { createWriteCoalescer, MAX_PENDING_WRITE_COALESCE_BYTES, + WRITE_COALESCE_BURST_MS, type WriteCoalescerOptions, } from "./writeCoalescer.ts"; @@ -87,6 +88,53 @@ test("microtask schedule mode flushes after the current turn without rAF", async 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> = []; diff --git a/components/terminal/runtime/writeCoalescer.ts b/components/terminal/runtime/writeCoalescer.ts index af72fb9a2..2f6ec53bb 100644 --- a/components/terminal/runtime/writeCoalescer.ts +++ b/components/terminal/runtime/writeCoalescer.ts @@ -6,10 +6,12 @@ * per chunk, which can tear TUI frames (missing box borders, clipped bottom * rows). Batching keeps rendering atomic per schedule turn. * - * Schedule modes (Tabby-inspired): + * Schedule modes (Tabby + Electerm-inspired): * - `raf`: wait for the next animation frame (best for alternate-screen TUIs) - * - `microtask`: flush after the current JS turn (normal-screen bulk / echo — - * closer to Tabby's direct write, still coalesces same-turn chunks) + * - `microtask`: flush after the current JS turn (same-turn merge only) + * - `burst`: idle output still flushes next microtask; writes that arrive + * inside a 16ms window after the last flush wait and merge (Electerm's + * attach-addon flood path). Never drops bytes. * * Ported from superset-sh/superset (issues #2241 / #2244): * apps/desktop/src/renderer/lib/terminal/write-coalescer.ts @@ -27,6 +29,11 @@ export { /** Maximum time pending output may wait for its primary scheduler. */ export const WRITE_COALESCE_FALLBACK_DRAIN_MS = 50; +/** + * Electerm-style burst window. After a flush, further chunks wait up to this + * long so a log flood becomes ~60 writes/s instead of one write per IPC turn. + */ +export const WRITE_COALESCE_BURST_MS = 16; export type WriteCoalescer = { push(chunk: string): void; @@ -38,7 +45,7 @@ export type WriteCoalescer = { dispose(): void; }; -export type WriteCoalesceScheduleMode = "raf" | "microtask"; +export type WriteCoalesceScheduleMode = "raf" | "microtask" | "burst"; export type WriteCoalesceScheduleContext = { /** Chunk about to be (or just) enqueued. */ @@ -63,6 +70,8 @@ export type WriteCoalescerOptions = { resolveScheduleMode?: (ctx: WriteCoalesceScheduleContext) => WriteCoalesceScheduleMode; getMaxPendingBytes?: () => number; shouldFlushScheduledFrame?: () => boolean; + now?: () => number; + burstWindowMs?: number; }; const scheduleRafFrame = (callback: () => void): (() => void) | null => { @@ -149,6 +158,7 @@ export const createWriteCoalescer = ( let cancelPendingSchedule: (() => void) | null = null; let scheduledMode: WriteCoalesceScheduleMode | null = null; let disposed = false; + let lastFlushTime = 0; const customScheduleFrame = options.scheduleFrame; const scheduleTimeout = options.scheduleTimeout ?? defaultScheduleTimeout; const fallbackDrainMs = options.fallbackDrainMs ?? WRITE_COALESCE_FALLBACK_DRAIN_MS; @@ -156,6 +166,12 @@ export const createWriteCoalescer = ( const getMaxPendingBytes = options.getMaxPendingBytes ?? (() => MAX_PENDING_WRITE_COALESCE_BYTES); const shouldFlushScheduledFrame = options.shouldFlushScheduledFrame ?? (() => true); + const now = options.now ?? (() => ( + typeof performance !== "undefined" && typeof performance.now === "function" + ? performance.now() + : Date.now() + )); + const burstWindowMs = options.burstWindowMs ?? WRITE_COALESCE_BURST_MS; const cancelScheduledDrain = (): void => { if (cancelPendingSchedule !== null) { @@ -208,6 +224,23 @@ export const createWriteCoalescer = ( flushSync(); }; + if (mode === "burst") { + const elapsed = lastFlushTime === 0 ? burstWindowMs : now() - lastFlushTime; + if (lastFlushTime > 0 && elapsed < burstWindowMs) { + const waitMs = Math.max(1, burstWindowMs - elapsed); + const cancel = scheduleTimeout(onScheduled, waitMs); + if (cancel === null) { + if (!shouldFlushScheduledFrame()) return; + flushSync(); + return; + } + cancelPendingSchedule = cancel; + scheduledMode = "burst"; + return; + } + mode = "microtask"; + } + const primaryCancel = scheduleByMode(mode, onScheduled, customScheduleFrame); const fallbackCancel = mode === "raf" && fallbackDrainMs > 0 @@ -234,6 +267,7 @@ export const createWriteCoalescer = ( const batch = pending.length === 1 ? pending[0]! : pending.join(""); pending = []; pendingBytes = 0; + lastFlushTime = now(); (writeOverride ?? write)(batch); }; @@ -245,6 +279,7 @@ export const createWriteCoalescer = ( const dropped = pendingBytes; pending = []; pendingBytes = 0; + lastFlushTime = 0; onDropped?.(dropped); }; @@ -275,7 +310,7 @@ export const createWriteCoalescer = ( // Upgrade microtask → rAF when a later chunk enters a TUI: the first shell // chunk may have scheduled a same-turn flush before the alt-screen CSI // arrived, which would tear the first repaint (Codex PR review). - if (scheduledMode === "microtask" && mode === "raf") { + if ((scheduledMode === "microtask" || scheduledMode === "burst") && mode === "raf") { cancelScheduledDrain(); armSchedule("raf"); } diff --git a/components/terminal/terminalHibernateRuntime.test.ts b/components/terminal/terminalHibernateRuntime.test.ts index a56dfbfb9..358275d5c 100644 --- a/components/terminal/terminalHibernateRuntime.test.ts +++ b/components/terminal/terminalHibernateRuntime.test.ts @@ -321,3 +321,22 @@ test("serializeTerminalForHibernate preserves plain text context for normal scre undefined, ]); }); + +test("serializeTerminalForHibernate waits for deferred history preparation", async () => { + const term = createFakeTerm("normal", 3, 5); + const events: string[] = []; + const result = await serializeTerminalForHibernate(term as never, { + serialize: () => { + events.push("serialize"); + return "serialized"; + }, + } as never, { + prepare: async () => { + await new Promise((resolve) => setTimeout(resolve, 1)); + events.push("prepare"); + }, + }); + + assert.equal(result.snapshot, "serialized"); + assert.deepEqual(events.slice(0, 2), ["prepare", "serialize"]); +}); diff --git a/components/terminal/terminalHibernateRuntime.ts b/components/terminal/terminalHibernateRuntime.ts index 6b331e2c7..bf540a3f8 100644 --- a/components/terminal/terminalHibernateRuntime.ts +++ b/components/terminal/terminalHibernateRuntime.ts @@ -189,8 +189,9 @@ async function serializeWithOptions( export async function serializeTerminalForHibernate( term: XTerm, serializeAddon: SerializeAddon, - options: { preferWasm?: boolean } = {}, + options: { preferWasm?: boolean; prepare?: () => Promise } = {}, ): Promise { + await options.prepare?.(); const { excludeAltBuffer, excludeModes, alternateScreen } = resolveHibernateSerializeOptions(term); const preferWasm = options.preferWasm === true; const rows = Math.max(1, term.rows); diff --git a/components/terminal/useTerminalEffects.ts b/components/terminal/useTerminalEffects.ts index 97de3d781..1ebf83da5 100644 --- a/components/terminal/useTerminalEffects.ts +++ b/components/terminal/useTerminalEffects.ts @@ -909,7 +909,11 @@ export function useTerminalEffects(ctx: TerminalEffectsContext) { if (!terminalDataCapturedRef.current && term && serializeAddon) { const preferWasm = resolveHibernatePreferWasmSerialize(terminalSettingsRef.current); try { - const payload = await serializeTerminalCloseFallback(term, serializeAddon, { preferWasm }); + const payload = await serializeTerminalCloseFallback(term, serializeAddon, { + preferWasm, + prepare: () => xtermRuntimeRef.current?.keywordHighlighter.prepareForSerialization() + ?? Promise.resolve(), + }); if (!isTerminalCloseGenerationCurrent( closeGeneration, terminalBootCloseGenerationRef.current, diff --git a/docs/plugin-platform/terminal-providers.md b/docs/plugin-platform/terminal-providers.md index 838ba0b31..e910ed68f 100644 --- a/docs/plugin-platform/terminal-providers.md +++ b/docs/plugin-platform/terminal-providers.md @@ -184,13 +184,14 @@ application Provider adapters as plugins: engine with global, case-insensitive matching; - decoration results are capped again after Provider fan-out at 16 active rules and 32 total patterns. Plugin matching examines at most the first 4096 - characters and retains at most 256 plugin matches for one logical line. A - wrapped logical line is matched only once per refresh before ranges are - projected onto its physical rows; plugin decoration is omitted for oversized - wrapped blocks that cannot be assembled safely. Patterns that can match an - empty string are rejected because they cannot produce a visible highlight. - Normal boot and hibernate wake share the same CWD-triggered decoration refresh - path; + characters of each incoming text segment and retains at most 256 plugin + matches per terminal write. Highlight colors are applied to already-parsed + cells; ordinary input and output only rematch dirty rows. When rules change, + the host restores original cell colors and recolors the visible viewport + immediately, then finishes scrollback in idle slices. Heavy output may skip + matching until one quiet-window catch-up. Patterns that can match an empty + string are rejected because they cannot produce a visible highlight. Normal + boot and hibernate wake share the same CWD-triggered decoration refresh path; - link and hover Providers receive one bounded physical xterm line and return exact zero-based ranges. Links are restricted to credential-free HTTP(S) URLs, reuse the host link-modifier policy, and render hover text with host diff --git a/infrastructure/config/xtermPerformance.ts b/infrastructure/config/xtermPerformance.ts index e6c5513ce..aa243d959 100644 --- a/infrastructure/config/xtermPerformance.ts +++ b/infrastructure/config/xtermPerformance.ts @@ -100,45 +100,10 @@ export const XTERM_PERFORMANCE_CONFIG = { largeBufferThreshold: 1024 * 1024, // 1MB }, - // Keyword highlighting optimizations + // Output-pressure quiet window shared by optional terminal side work. highlighting: { - // Debounce time for viewport scanning (ms) - // Higher values = better scrolling performance, but slower highlight "catch up" - debounceMs: 100, - // Minimum interval between immediate (rAF) refreshes in ms. - // Prevents heavy output (e.g. tail -f) from refreshing every frame. - immediateMinIntervalMs: 16, - // Number of unique line scan results to keep cached. - cacheEntries: 1200, - // Retain matched-line markers across nearby scrollback without allowing a - // broad rule to register unbounded xterm trim listeners. - persistentDecorationViewports: 20, - minPersistentDecorationLines: 200, - maxPersistentDecorationLines: 1200, - // Keep decorations for lines just outside the viewport so small scrolls - // don't constantly dispose/recreate them. Scales with current terminal rows. - overscanViewportRatio: 2.0, - // Dirty scan padding around cursor/viewport deltas for write bursts. - dirtyScanPadding: 2, - // Dynamic dirty-line cap scales with viewport rows. - dirtyLinesPerViewportRow: 6, - // Clamp the dynamic dirty-line cap to avoid extremes. - minDirtyLines: 200, - maxDirtyLines: 1200, - // Max processing time per refresh pass when handling dirty lines (ms). - writeRefreshBudgetMs: 4, - // Process dirty contiguous lines in chunks so budget checks can preempt. - dirtySegmentChunkSize: 48, - // Keep highlighting deprioritized briefly after a large output burst. - // Longer quiet window lets xterm paint bulk dumps (cat/yes/tail) without - // competing decoration scans every few hundred ms. + // Let large output settle before deferred work catches up. largeOutputQuietMs: 480, - // Give interactive typing priority over keyword highlight catch-up. - inputQuietMs: 180, - // Extra debounce while large-output / long-line pressure is active. - largeOutputDebounceMs: 280, - // Floor for immediate refresh interval under output pressure. - largeOutputImmediateMinIntervalMs: 120, }, }; diff --git a/package.json b/package.json index 4ec1a08c7..412ef0009 100644 --- a/package.json +++ b/package.json @@ -64,7 +64,8 @@ "test:ssh-mfa-models": "node --test electron/bridges/sshMfaModels.live.test.cjs", "test:ssh-mfa-models:live": "SSH_MFA_LIVE=1 node --test electron/bridges/sshMfaModels.live.test.cjs", "test:xterm-webgl-overflow": "electron scripts/xterm-webgl-atlas-overflow.live.test.cjs", - "test:xterm-decoration-performance": "electron scripts/xterm-decoration-performance.live.test.cjs" + "test:xterm-keyword-highlight-performance": "electron scripts/xterm-keyword-highlight-performance.live.test.cjs", + "test:xterm-keyword-highlight-throughput": "electron scripts/xterm-keyword-highlight-throughput.live.test.cjs" }, "dependencies": { "@ai-sdk/anthropic": "^4.0.0", diff --git a/scripts/github-workflow-ci.test.cjs b/scripts/github-workflow-ci.test.cjs index 1f391a24c..a42e5c817 100644 --- a/scripts/github-workflow-ci.test.cjs +++ b/scripts/github-workflow-ci.test.cjs @@ -76,7 +76,7 @@ test("PR validation runs once per commit and includes a production build", () => assert.match(testWorkflow, /sudo apt-get install -y fish xvfb/); assert.match( testWorkflow, - /- name: Test terminal decoration performance\s*\n\s*env:\s*\n\s*NETCATTY_TERMINAL_PERF_SHOW_WINDOW: "1"\s*\n\s*# GitHub-hosted runners do not configure Electron's SUID sandbox helper\.\s*\n\s*run: xvfb-run -a \.\/node_modules\/\.bin\/electron --no-sandbox scripts\/xterm-decoration-performance\.live\.test\.cjs/, + /- name: Test terminal keyword highlight performance\s*\n\s*env:\s*\n\s*NETCATTY_TERMINAL_PERF_SHOW_WINDOW: "1"\s*\n\s*# GitHub-hosted runners do not configure Electron's SUID sandbox helper\.\s*\n\s*run: xvfb-run -a \.\/node_modules\/\.bin\/electron --no-sandbox scripts\/xterm-keyword-highlight-performance\.live\.test\.cjs/, ); assert.match(testWorkflow, /- name: Build\s*\n\s*run: npm run build/); assert.doesNotMatch(testWorkflow, /\n mosh-windows-conpty:/); diff --git a/scripts/xterm-decoration-performance.live.test.cjs b/scripts/xterm-decoration-performance.live.test.cjs deleted file mode 100644 index ee431faa3..000000000 --- a/scripts/xterm-decoration-performance.live.test.cjs +++ /dev/null @@ -1,206 +0,0 @@ -"use strict"; - -/* global process, __dirname, console */ - -if (!process.versions.electron) { - const test = require("node:test"); - test("xterm keeps dense keyword-style decorations responsive", { - skip: "run with Electron so the real DOM renderer is available", - }, () => {}); -} else { - const assert = require("node:assert/strict"); - const fs = require("node:fs"); - const path = require("node:path"); - const electron = require("electron"); - const esbuild = require("esbuild"); - const tempDirBridge = require("../electron/bridges/tempDirBridge.cjs"); - - const appRoot = path.resolve(__dirname, ".."); - const showWindow = process.env.NETCATTY_TERMINAL_PERF_SHOW_WINDOW === "1"; - const userData = fs.mkdtempSync(`${tempDirBridge.getTempFilePath("xterm-decoration-perf")}-`); - electron.app.setPath("userData", userData); - electron.app.on("window-all-closed", () => {}); - let window = null; - - const cleanup = (exitCode) => { - if (window && !window.isDestroyed()) { - window.destroy(); - } - try { - fs.rmSync(userData, { recursive: true, force: true }); - } catch (error) { - console.warn("Unable to remove xterm performance test data:", error); - } finally { - electron.app.exit(exitCode); - } - }; - - void electron.app.whenReady().then(async () => { - window = new electron.BrowserWindow({ - show: showWindow, - width: 900, - height: 560, - paintWhenInitiallyHidden: true, - webPreferences: { - backgroundThrottling: false, - contextIsolation: false, - nodeIntegration: true, - sandbox: false, - }, - }); - await window.loadURL( - "data:text/html;charset=utf-8," + encodeURIComponent( - "
", - ), - ); - - const xtermPath = require.resolve("@xterm/xterm", { paths: [appRoot] }); - const keywordHighlighterPath = path.join(appRoot, "components/terminal/keywordHighlight.ts"); - const keywordHighlighterBundle = esbuild.buildSync({ - entryPoints: [keywordHighlighterPath], - bundle: true, - format: "cjs", - platform: "browser", - target: "chrome142", - write: false, - }).outputFiles[0].text; - const result = await window.webContents.executeJavaScript(`(async () => { - const { Terminal } = require(${JSON.stringify(xtermPath)}); - const highlighterModule = { exports: {} }; - ((module, exports) => { - ${keywordHighlighterBundle} - })(highlighterModule, highlighterModule.exports); - const { KeywordHighlighter } = highlighterModule.exports; - const term = new Terminal({ - allowProposedApi: true, - cols: 80, - cursorBlink: false, - rendererType: "dom", - rows: 30, - scrollback: 1000, - }); - term.open(document.getElementById("terminal")); - - const waitForPaint = () => new Promise(resolve => { - requestAnimationFrame(() => requestAnimationFrame(resolve)); - }); - const waitForRender = (trigger, label) => new Promise((resolve, reject) => { - const startedAt = performance.now(); - const timeout = setTimeout(() => { - disposable.dispose(); - reject(new Error("timed out waiting for terminal render: " + label)); - }, 15000); - const disposable = term.onRender(() => { - disposable.dispose(); - waitForPaint().then(() => { - clearTimeout(timeout); - resolve(performance.now() - startedAt); - }, reject); - }); - trigger(); - }); - const writeAndWait = data => new Promise(resolve => term.write(data, resolve)); - const waitForCondition = async (condition, label) => { - const deadline = performance.now() + 15000; - while (!condition()) { - if (performance.now() >= deadline) { - throw new Error("timed out waiting for " + label); - } - await waitForPaint(); - } - }; - - let history = ""; - for (let line = 0; line < 500; line += 1) { - history += "INFO WARN ERROR SUCCESS DEBUG completed failed critical\\r\\n"; - } - await writeAndWait(history); - - const highlighter = new KeywordHighlighter(term); - highlighter.setRules([ - { enabled: true, patterns: ["INFO"], color: "#60a5fa" }, - { enabled: true, patterns: ["WARN"], color: "#fbbf24" }, - { enabled: true, patterns: ["ERROR"], color: "#f87171" }, - { enabled: true, patterns: ["SUCCESS"], color: "#4ade80" }, - { enabled: true, patterns: ["DEBUG"], color: "#a78bfa" }, - { enabled: true, patterns: ["completed"], color: "#2dd4bf" }, - { enabled: true, patterns: ["failed"], color: "#fb7185" }, - { enabled: true, patterns: ["critical"], color: "#f43f5e" }, - ], true); - const countNetcattyDecorations = () => Array.from(highlighter.lineDecorations.values()) - .reduce((count, state) => count + state.decorations.length, 0); - await waitForCondition( - () => countNetcattyDecorations() >= term.rows * 8, - "Netcatty keyword decorations", - ); - const netcattyDecorationCount = countNetcattyDecorations(); - const netcattyRefreshMs = await waitForRender( - () => term.refresh(0, term.rows - 1), - "Netcatty keyword highlight paint", - ); - highlighter.dispose(); - await waitForPaint(); - - const cursorLine = term.buffer.normal.baseY + term.buffer.normal.cursorY; - const markers = []; - const decorations = []; - for (let line = term.buffer.normal.length - 500; line < term.buffer.normal.length; line += 1) { - const marker = term.registerMarker(line - cursorLine); - if (!marker) continue; - markers.push(marker); - for (let x = 0; x < term.cols; x += 2) { - const decoration = term.registerDecoration({ - marker, - x, - width: 1, - foregroundColor: "#f87171", - }); - if (decoration) decorations.push(decoration); - } - } - - const registrationPaintMs = await waitForRender( - () => term.refresh(0, term.rows - 1), - "registration paint", - ); - const refreshMs = []; - for (let iteration = 0; iteration < 3; iteration += 1) { - refreshMs.push(await waitForRender( - () => term.refresh(0, term.rows - 1), - "measured refresh " + iteration, - )); - } - - const state = { - decorationCount: decorations.length, - markerCount: markers.length, - netcattyDecorationCount, - netcattyRefreshMs, - registrationPaintMs, - refreshMs, - worstRefreshMs: Math.max(...refreshMs), - }; - decorations.forEach(decoration => decoration.dispose()); - markers.forEach(marker => marker.dispose()); - term.dispose(); - return state; - })()`); - - assert.equal(result.markerCount, 500, JSON.stringify(result)); - assert.equal(result.decorationCount, 20000, JSON.stringify(result)); - assert.ok(result.netcattyDecorationCount >= 240, JSON.stringify(result)); - assert.ok( - result.netcattyRefreshMs < 150, - `Netcatty keyword highlighting blocked terminal paint: ${JSON.stringify(result)}`, - ); - assert.ok( - result.worstRefreshMs < 150, - `dense keyword-style decorations blocked terminal repaint: ${JSON.stringify(result)}`, - ); - process.stdout.write(`XTERM_DECORATION_PERFORMANCE_OK ${JSON.stringify(result)}\n`); - cleanup(0); - }).catch((error) => { - console.error(error); - cleanup(1); - }); -} diff --git a/scripts/xterm-keyword-highlight-performance.live.test.cjs b/scripts/xterm-keyword-highlight-performance.live.test.cjs new file mode 100644 index 000000000..4be069f1a --- /dev/null +++ b/scripts/xterm-keyword-highlight-performance.live.test.cjs @@ -0,0 +1,174 @@ +"use strict"; + +/* global process, __dirname, console */ + +if (!process.versions.electron) { + const test = require("node:test"); + test("inline keyword highlighting stays responsive", { + skip: "run with Electron so the real WebGL renderer is available", + }, () => {}); +} else { + const assert = require("node:assert/strict"); + const fs = require("node:fs"); + const path = require("node:path"); + const electron = require("electron"); + const esbuild = require("esbuild"); + const tempDirBridge = require("../electron/bridges/tempDirBridge.cjs"); + + const appRoot = path.resolve(__dirname, ".."); + const showWindow = process.env.NETCATTY_TERMINAL_PERF_SHOW_WINDOW === "1"; + const userData = fs.mkdtempSync(`${tempDirBridge.getTempFilePath("xterm-keyword-highlight-perf")}-`); + electron.app.setPath("userData", userData); + electron.app.on("window-all-closed", () => {}); + let window = null; + + const cleanup = (exitCode) => { + if (window && !window.isDestroyed()) window.destroy(); + try { + fs.rmSync(userData, { recursive: true, force: true }); + } catch (error) { + console.warn("Unable to remove xterm performance test data:", error); + } finally { + electron.app.exit(exitCode); + } + }; + + void electron.app.whenReady().then(async () => { + window = new electron.BrowserWindow({ + show: showWindow, + width: 1000, + height: 640, + paintWhenInitiallyHidden: true, + webPreferences: { + backgroundThrottling: false, + contextIsolation: false, + nodeIntegration: true, + sandbox: false, + }, + }); + await window.loadURL( + "data:text/html;charset=utf-8," + encodeURIComponent( + "
", + ), + ); + + const xtermPath = require.resolve("@xterm/xterm", { paths: [appRoot] }); + const webglPath = require.resolve("@xterm/addon-webgl", { paths: [appRoot] }); + const serializePath = require.resolve("@xterm/addon-serialize", { paths: [appRoot] }); + const highlighterPath = path.join(appRoot, "components/terminal/keywordHighlight.ts"); + const pressurePath = path.join(appRoot, "components/terminal/runtime/terminalOutputPressure.ts"); + const highlighterBundle = esbuild.buildSync({ + stdin: { + contents: [ + `export * from ${JSON.stringify(highlighterPath)};`, + `export { noteTerminalOutputPressureData } from ${JSON.stringify(pressurePath)};`, + ].join("\n"), + loader: "ts", + resolveDir: appRoot, + }, + bundle: true, + format: "cjs", + platform: "browser", + target: "chrome142", + write: false, + }).outputFiles[0].text; + + const result = await window.webContents.executeJavaScript(`(async () => { + const { Terminal } = require(${JSON.stringify(xtermPath)}); + const { WebglAddon } = require(${JSON.stringify(webglPath)}); + const { SerializeAddon } = require(${JSON.stringify(serializePath)}); + const highlighterModule = { exports: {} }; + ((module, exports) => { ${highlighterBundle} })(highlighterModule, highlighterModule.exports); + const { KeywordHighlighter, noteTerminalOutputPressureData } = highlighterModule.exports; + const term = new Terminal({ + allowProposedApi: true, + cols: 120, + cursorBlink: false, + rows: 40, + scrollback: 10000, + }); + term.open(document.getElementById("terminal")); + let renderer = "dom"; + try { + term.loadAddon(new WebglAddon()); + renderer = "webgl"; + } catch {} + const serializer = new SerializeAddon(); + term.loadAddon(serializer); + const highlighter = new KeywordHighlighter(term); + const redRules = [{ + id: "error", + label: "Error", + patterns: ["ERROR", "failed", "10\\\\.2\\\\.\\\\d+\\\\.\\\\d+"], + color: "#F87171", + enabled: true, + }]; + const blueRules = redRules.map(rule => ({ ...rule, color: "#60A5FA" })); + highlighter.setRules(redRules, true); + const write = data => new Promise(resolve => term.write(data, resolve)); + const waitPaint = () => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))); + let history = ""; + for (let line = 0; line < 10000; line += 1) { + history += "2026-08-13 worker=" + (line % 32) + " ERROR failed from 10.2." + (line % 255) + "." + ((line * 7) % 255) + "\\r\\n"; + } + + const initialStart = performance.now(); + noteTerminalOutputPressureData(term, history); + await write(history); + await waitPaint(); + const initialWriteMs = performance.now() - initialStart; + await new Promise(resolve => setTimeout(resolve, 650)); + await highlighter.whenSettled(); + const rebuildsBeforeEnter = highlighter.rebuildCount; + + const enterStart = performance.now(); + const prompt = "\\r\\nplain prompt # "; + noteTerminalOutputPressureData(term, prompt); + await write(prompt); + await waitPaint(); + const enterWriteMs = performance.now() - enterStart; + await new Promise(resolve => setTimeout(resolve, 650)); + await highlighter.whenSettled(); + const enterRebuildCount = highlighter.rebuildCount; + + const rebuildStart = performance.now(); + highlighter.setRules(blueRules, true); + await highlighter.whenSettled(); + await waitPaint(); + const rebuildMs = performance.now() - rebuildStart; + + const serialized = serializer.serialize({ scrollback: 10000 }); + const pristine = highlighter.serializeAddon.serialize({ scrollback: 10000 }); + const state = { + renderer, + rawChars: history.length, + initialWriteMs, + rebuildsBeforeEnter, + enterWriteMs, + enterRebuildCount, + rebuildMs, + rebuildCount: highlighter.rebuildCount, + blueMatchCount: (serialized.match(/38;2;96;165;250m/g) || []).length, + pristineHasNetcattyColor: /38;2;(248;113;113|96;165;250)m/.test(pristine), + }; + highlighter.dispose(); + term.dispose(); + return state; + })()`); + + if (process.env.NETCATTY_TERMINAL_PERF_REQUIRE_WEBGL === "1") { + assert.equal(result.renderer, "webgl", JSON.stringify(result)); + } + assert.equal(result.enterRebuildCount, result.rebuildsBeforeEnter, JSON.stringify(result)); + assert.equal(result.rebuildCount, result.rebuildsBeforeEnter + 1, JSON.stringify(result)); + assert.ok(result.blueMatchCount >= 10000, JSON.stringify(result)); + assert.equal(result.pristineHasNetcattyColor, false, JSON.stringify(result)); + assert.ok(result.enterWriteMs < 150, `Enter write regressed: ${JSON.stringify(result)}`); + assert.ok(result.rebuildMs < 1000, `10k-line rule rebuild regressed: ${JSON.stringify(result)}`); + process.stdout.write(`XTERM_KEYWORD_HIGHLIGHT_PERFORMANCE_OK ${JSON.stringify(result)}\n`); + cleanup(0); + }).catch((error) => { + console.error(error); + cleanup(1); + }); +} diff --git a/scripts/xterm-keyword-highlight-throughput.live.test.cjs b/scripts/xterm-keyword-highlight-throughput.live.test.cjs new file mode 100644 index 000000000..918dc8e17 --- /dev/null +++ b/scripts/xterm-keyword-highlight-throughput.live.test.cjs @@ -0,0 +1,358 @@ +"use strict"; + +/* global process, __dirname, console */ + +if (!process.versions.electron) { + const test = require("node:test"); + test("keyword highlighting keeps sustained output responsive", { + skip: "run with Electron so the real WebGL renderer is available", + }, () => {}); +} else { + const assert = require("node:assert/strict"); + const childProcess = require("node:child_process"); + const fs = require("node:fs"); + const path = require("node:path"); + const electron = require("electron"); + const esbuild = require("esbuild"); + const tempDirBridge = require("../electron/bridges/tempDirBridge.cjs"); + + const appRoot = path.resolve(__dirname, ".."); + const mainRef = process.env.NETCATTY_TERMINAL_PERF_MAIN_REF ?? "origin/main"; + const chunkCount = Number.parseInt(process.env.NETCATTY_TERMINAL_PERF_CHUNKS ?? "1600", 10); + const roundCount = Number.parseInt(process.env.NETCATTY_TERMINAL_PERF_ROUNDS ?? "3", 10); + const scrollback = Number.parseInt( + process.env.NETCATTY_TERMINAL_PERF_SCROLLBACK ?? "50000", + 10, + ); + const userData = fs.mkdtempSync(`${tempDirBridge.getTempFilePath("xterm-highlight-throughput")}-`); + electron.app.setPath("userData", userData); + electron.app.commandLine.appendSwitch("js-flags", "--expose-gc"); + electron.app.on("window-all-closed", () => {}); + let window = null; + + const cleanup = (exitCode) => { + if (window && !window.isDestroyed()) window.destroy(); + try { + fs.rmSync(userData, { recursive: true, force: true }); + } catch (error) { + console.warn("Unable to remove xterm throughput test data:", error); + } finally { + electron.app.exit(exitCode); + } + }; + + const buildModule = (source, resolveDir, plugins = []) => esbuild.buildSync({ + stdin: { contents: source, loader: "ts", resolveDir }, + bundle: true, + format: "cjs", + platform: "browser", + target: "chrome142", + write: false, + plugins, + }).outputFiles[0].text; + + const buildMainModule = async () => { + const entryPath = "components/terminal/__keywordHighlightThroughputEntry.ts"; + const entrySource = [ + 'export * from "./keywordHighlight";', + 'export { noteTerminalOutputPressureData } from "./runtime/terminalOutputPressure";', + ].join("\n"); + const resolveMainFile = (repoPath) => { + const candidates = repoPath === entryPath + ? [entryPath] + : [repoPath, `${repoPath}.ts`, `${repoPath}.tsx`, `${repoPath}/index.ts`, `${repoPath}/index.tsx`]; + for (const candidate of candidates) { + if (candidate === entryPath) return candidate; + const exists = childProcess.spawnSync( + "git", + ["cat-file", "-e", `${mainRef}:${candidate}`], + { cwd: appRoot, stdio: "ignore" }, + ).status === 0; + if (exists) return candidate; + } + throw new Error(`Unable to resolve ${mainRef} source: ${repoPath}`); + }; + const readMainFile = (repoPath) => repoPath === entryPath + ? entrySource + : childProcess.execFileSync("git", ["show", `${mainRef}:${repoPath}`], { + cwd: appRoot, + encoding: "utf8", + }); + const mainPlugin = { + name: "main-source", + setup(build) { + build.onResolve({ filter: /.*/ }, (args) => { + if (args.kind !== "entry-point") return undefined; + return { path: entryPath, namespace: "main-source" }; + }); + build.onResolve({ filter: /^\.\.?\// }, (args) => ({ + path: resolveMainFile( + path.posix.normalize(path.posix.join(path.posix.dirname(args.importer), args.path)), + ), + namespace: "main-source", + })); + build.onLoad({ filter: /.*/, namespace: "main-source" }, (args) => ({ + contents: readMainFile(args.path), + loader: args.path.endsWith(".json") ? "json" : args.path.endsWith(".tsx") ? "tsx" : "ts", + resolveDir: path.posix.dirname(args.path), + })); + }, + }; + return (await esbuild.build({ + entryPoints: [entryPath], + bundle: true, + format: "cjs", + platform: "browser", + target: "chrome142", + write: false, + plugins: [mainPlugin], + })).outputFiles[0].text; + }; + + void electron.app.whenReady().then(async () => { + const oldBundle = await buildMainModule(); + const currentBundle = buildModule([ + `export * from ${JSON.stringify(path.join(appRoot, "components/terminal/keywordHighlight.ts"))};`, + `export { noteTerminalOutputPressureData } from ${JSON.stringify(path.join(appRoot, "components/terminal/runtime/terminalOutputPressure.ts"))};`, + ].join("\n"), appRoot); + + window = new electron.BrowserWindow({ + show: process.env.NETCATTY_TERMINAL_PERF_SHOW_WINDOW === "1", + width: 1000, + height: 640, + paintWhenInitiallyHidden: true, + webPreferences: { + backgroundThrottling: false, + contextIsolation: false, + nodeIntegration: true, + sandbox: false, + }, + }); + await window.loadURL( + "data:text/html;charset=utf-8," + encodeURIComponent( + "
", + ), + ); + + const xtermPath = require.resolve("@xterm/xterm", { paths: [appRoot] }); + const webglPath = require.resolve("@xterm/addon-webgl", { paths: [appRoot] }); + const result = await window.webContents.executeJavaScript(`(async () => { + const { Terminal } = require(${JSON.stringify(xtermPath)}); + const { WebglAddon } = require(${JSON.stringify(webglPath)}); + const loadBundle = source => { + const loaded = { exports: {} }; + ((module, exports) => { eval(source); })(loaded, loaded.exports); + return loaded.exports; + }; + const oldModule = loadBundle(${JSON.stringify(oldBundle)}); + const currentModule = loadBundle(${JSON.stringify(currentBundle)}); + const rules = [ + { id: "info", label: "Info", patterns: ["INFO"], color: "#60A5FA", enabled: true }, + { id: "warn", label: "Warn", patterns: ["WARN"], color: "#FBBF24", enabled: true }, + { id: "error", label: "Error", patterns: ["ERROR", "failed"], color: "#F87171", enabled: true }, + { id: "ip", label: "IP", patterns: ["10\\\\.2\\\\.\\\\d+\\\\.\\\\d+"], color: "#4ADE80", enabled: true }, + ]; + const makeChunk = index => { + let chunk = ""; + for (let line = 0; line < 64; line += 1) { + chunk += "2026-08-13 INFO worker=" + (line % 32) + " WARN ERROR failed from 10.2." + + ((index + line) % 255) + "." + ((index * 7 + line) % 255) + " payload=" + + "x".repeat(24) + "\\r\\n"; + } + return chunk; + }; + const chunks = Array.from({ length: ${chunkCount} }, (_, index) => makeChunk(index)); + const totalChars = chunks.reduce((total, chunk) => total + chunk.length, 0); + const wait = ms => new Promise(resolve => setTimeout(resolve, ms)); + + const run = async kind => { + document.getElementById("terminal").replaceChildren(); + globalThis.gc?.(); + await wait(20); + const v8 = require("node:v8"); + const heapBefore = v8.getHeapStatistics().used_heap_size; + const term = new Terminal({ + allowProposedApi: true, + cols: 120, + cursorBlink: false, + rows: 40, + scrollback: ${scrollback}, + }); + term.open(document.getElementById("terminal")); + let renderer = "dom"; + try { + term.loadAddon(new WebglAddon()); + renderer = "webgl"; + } catch {} + const selectedModule = kind === "old" ? oldModule : currentModule; + const Highlighter = kind === "old" + ? oldModule.KeywordHighlighter + : currentModule.KeywordHighlighter; + const highlighter = kind === "raw" ? null : new Highlighter(term); + highlighter?.setRules(rules, true); + const sustainedOnly = process.env.NETCATTY_TERMINAL_PERF_SUSTAINED_ONLY === "1"; + let maxPendingPristineBytes = 0; + const pendingSample = setInterval(() => { + maxPendingPristineBytes = Math.max( + maxPendingPristineBytes, + highlighter?.pendingPristineBytes ?? 0, + ); + }, 5); + const write = data => new Promise(resolve => term.write(data, resolve)); + const callbackLatencies = []; + const heartbeatLatencies = []; + let heartbeatAt = performance.now(); + const heartbeat = setInterval(() => { + const now = performance.now(); + heartbeatLatencies.push(now - heartbeatAt); + heartbeatAt = now; + }, 10); + let renders = 0; + const renderDisposable = term.onRender(() => { renders += 1; }); + const streamStarted = performance.now(); + for (let index = 0; index < chunks.length; index += 1) { + const chunk = chunks[index]; + selectedModule.noteTerminalOutputPressureData(term, chunk); + const callbackStarted = performance.now(); + await write(chunk); + callbackLatencies.push(performance.now() - callbackStarted); + if (index % 16 === 15) await wait(0); + } + const streamMs = performance.now() - streamStarted; + const rendersAtStreamEnd = renders; + const quietStarted = performance.now(); + await wait(sustainedOnly ? 0 : 700); + const quietDelayMs = performance.now() - quietStarted; + const streamHeartbeatCount = heartbeatLatencies.length; + const streamMaxHeartbeatMs = Math.max(0, ...heartbeatLatencies); + const rendersBeforeSettle = renders; + const settleStarted = performance.now(); + if (!sustainedOnly) await highlighter?.whenSettled?.(); + const settleWaitMs = performance.now() - settleStarted; + const quietWorkMs = performance.now() - quietStarted - (sustainedOnly ? 0 : 700); + let paintTimedOut = false; + if (!sustainedOnly) { + await Promise.race([ + new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))), + wait(1000).then(() => { paintTimedOut = true; }), + ]); + } + const quietCatchUpMs = performance.now() - quietStarted - (sustainedOnly ? 0 : 700); + clearInterval(heartbeat); + clearInterval(pendingSample); + globalThis.gc?.(); + await wait(20); + const heapAfter = v8.getHeapStatistics().used_heap_size; + callbackLatencies.sort((left, right) => left - right); + const percentile = value => callbackLatencies[Math.min( + callbackLatencies.length - 1, + Math.floor(callbackLatencies.length * value), + )]; + const state = { + kind, + renderer, + streamMs, + mibPerSecond: totalChars / 1024 / 1024 / (streamMs / 1000), + callbackP50Ms: percentile(0.5), + callbackP95Ms: percentile(0.95), + callbackP99Ms: percentile(0.99), + maxHeartbeatMs: streamMaxHeartbeatMs, + maxCatchUpHeartbeatMs: Math.max(0, ...heartbeatLatencies.slice(streamHeartbeatCount)), + quietCatchUpMs, + quietWorkMs, + quietDelayMs, + settleWaitMs, + paintTimedOut, + rendersDuringStream: rendersAtStreamEnd, + rendersDuringSettle: renders - rendersBeforeSettle, + heapDeltaMiB: (heapAfter - heapBefore) / 1024 / 1024, + rebuildCount: highlighter?.rebuildCount ?? 0, + rebuildTimings: highlighter?.lastRebuildTimings ?? {}, + maxPendingPristineBytes, + }; + renderDisposable.dispose(); + highlighter?.dispose(); + term.dispose(); + return state; + }; + + const rounds = []; + for (let round = 0; round < ${roundCount}; round += 1) { + for (const kind of ["raw", "old", "new"]) rounds.push(await run(kind)); + } + return { totalChars, chunks: chunks.length, rounds }; + })()`, true); + + if (process.env.NETCATTY_TERMINAL_PERF_REQUIRE_WEBGL === "1") { + for (const round of result.rounds) assert.equal(round.renderer, "webgl", JSON.stringify(round)); + } + const median = values => values.sort((left, right) => left - right)[Math.floor(values.length / 2)]; + const byKind = kind => result.rounds.filter(round => round.kind === kind); + const oldStreamMs = median(byKind("old").map(round => round.streamMs)); + const newStreamMs = median(byKind("new").map(round => round.streamMs)); + const oldP99Ms = median(byKind("old").map(round => round.callbackP99Ms)); + const newP99Ms = median(byKind("new").map(round => round.callbackP99Ms)); + const oldHeartbeatMs = median(byKind("old").map(round => round.maxHeartbeatMs)); + const newHeartbeatMs = median(byKind("new").map(round => round.maxHeartbeatMs)); + const newCatchUpHeartbeatMs = median(byKind("new").map(round => round.maxCatchUpHeartbeatMs)); + const newQuietCatchUpMs = median(byKind("new").map(round => round.quietCatchUpMs)); + // Catch-up is deliberately deferred until output becomes quiet. Keep a + // strict event-loop stall limit, while allowing total work to scale with + // the retained history size (5s at 10k lines, 10s at 50k lines). + const maxQuietCatchUpMs = Math.max(5000, scrollback / 5); + const rawStreamMs = median(byKind("raw").map(round => round.streamMs)); + const rawP99Ms = median(byKind("raw").map(round => round.callbackP99Ms)); + assert.ok( + newStreamMs <= oldStreamMs * 1.1, + `new sustained throughput regressed more than 10%: ${JSON.stringify(result)}`, + ); + assert.ok( + newP99Ms <= oldP99Ms * 1.15, + `new p99 write latency regressed more than 15%: ${JSON.stringify(result)}`, + ); + assert.ok( + newHeartbeatMs <= Math.max(75, oldHeartbeatMs * 3), + `new event-loop stall regressed: ${JSON.stringify(result)}`, + ); + assert.ok( + newCatchUpHeartbeatMs <= 350, + `quiet catch-up blocked the event loop for over 350 ms: ${JSON.stringify(result)}`, + ); + // Product gate is vs main decorations (10% above). Raw xterm is a sanity + // bound only: cell-color wrap + DOM CI is typically ~15-18% over raw. + assert.ok( + newStreamMs <= rawStreamMs * 1.25, + `new sustained throughput regressed more than 25% versus raw xterm: ${JSON.stringify(result)}`, + ); + assert.ok( + newP99Ms <= Math.max(10, rawP99Ms * 1.25), + `new p99 write latency regressed versus raw xterm: ${JSON.stringify(result)}`, + ); + assert.ok( + newQuietCatchUpMs <= maxQuietCatchUpMs, + `quiet-period catch-up exceeded ${maxQuietCatchUpMs} ms: ${JSON.stringify(result)}`, + ); + if (process.env.NETCATTY_TERMINAL_PERF_SUSTAINED_ONLY !== "1") { + assert.equal( + byKind("new").every(round => round.rebuildCount === 1), + true, + `bulk output must catch up exactly once after becoming quiet: ${JSON.stringify(result)}`, + ); + assert.equal( + byKind("new").every(round => !round.paintTimedOut && round.rendersDuringSettle <= 1), + true, + `quiet catch-up must repaint atomically: ${JSON.stringify(result)}`, + ); + } + assert.equal( + byKind("new").every(round => round.maxPendingPristineBytes <= 12 * 1024 * 1024), + true, + `pristine backlog must stay bounded: ${JSON.stringify(result)}`, + ); + process.stdout.write(`XTERM_KEYWORD_HIGHLIGHT_THROUGHPUT ${JSON.stringify(result)}\n`); + cleanup(0); + }).catch((error) => { + console.error(error); + cleanup(1); + }); +}