Add cell color override API for text recoloring

Add setCellColorOverrides/clearCellColorOverrides to the terminal API,
backed by a per-line sparse override store consumed by the DOM renderer's
row factory. Covered cells render their original text in the given color,
with override equality participating in span merging so runs break only at
color boundaries. Overrides are keyed by absolute buffer line of the active
buffer; refresh is limited to the affected viewport rows.

This gives embedders a cheap way to recolor terminal text (e.g. keyword
highlighting) without decoration objects, which fragment text spans and
carry per-cell lookup cost in the DOM renderer, and which are force-hidden
while the alternate buffer is active.
This commit is contained in:
ys-ll
2026-09-20 19:20:47 +08:00
parent f447274f43
commit d07813da37
10 changed files with 195 additions and 5 deletions
+29
View File
@@ -612,6 +612,19 @@ declare module '@xterm/xterm' {
overviewRulerOptions?: IDecorationOverviewRulerOptions;
}
/**
* A contiguous cell range on one buffer line whose text should be rendered
* in a specific color, used with {@link Terminal.setCellColorOverrides}.
*/
export interface ICellColorSpan {
/** Zero-based column of the first cell. */
col: number;
/** Number of cells covered (wide characters count as 2 cells). */
width: number;
/** CSS color string (#rrggbb, rgb(...), etc.). */
color: string;
}
/**
* The set of localizable strings.
*/
@@ -1156,6 +1169,22 @@ declare module '@xterm/xterm' {
*/
registerDecoration(decorationOptions: IDecorationOptions): IDecoration | undefined;
/**
* Recolor a contiguous range of cells on one buffer line by drawing the
* covered text in the given color. Pass null for spans to clear the line.
* Line indexes are absolute within the active buffer; the caller must
* clear/re-set overrides when indexes shift (scrollback trim, resize
* reflow) or when the alternate buffer changes.
* @param lineY The absolute buffer line index (ydisp-independent).
* @param spans The cell ranges and colors to apply, or null to clear.
*/
setCellColorOverrides(lineY: number, spans: ICellColorSpan[] | null): void;
/**
* Clears all cell color overrides set by setCellColorOverrides.
*/
clearCellColorOverrides(): void;
/**
* Gets whether the terminal has an active selection.
*/