xonecas.io
6533
Yo

yoctomarkdown / commit 6e23f7a

fix: replace DECSC/DECRC with eraseLines pattern for scroll-safe partial redraw

Replace \x1b7/\x1b8 (DECSC/DECRC) cursor save/restore with the standard
eraseLines pattern used by log-update and ansi-escapes (29M weekly
downloads). The old approach saved absolute cursor positions which
became stale when terminal scrolling shifted them, causing duplicate
lines in the streaming API.

The new approach uses only relative cursor movement:
  - \x1b[2K (erase entire line)
  - \x1b[1A (cursor up)
  - \x1b[G  (cursor to column 1)

This is immune to terminal scroll since all movement is relative.
Visual line count is tracked to handle wrapped partials correctly.

Also improves the test terminal simulator to handle all standard CSI
sequences (A/B/C/D/G/J/K) via a single parser instead of ad-hoc
matching.

xonecas2026-03-16 6e23f7afc7c93a58b6ec00fa9e0b34991687bfb7 parent dd8fba6

2 files changed

src/index.ts+53−13
@@ -12,6 +12,20 @@ export interface Highlighter {
1212 end(): string;
1313 }
1414
15+function resolveColumns(options?: Options): number {
16+ const wrap = options?.wordWrap ?? "auto";
17+ if (typeof wrap === "number" && wrap > 0) return wrap;
18+ if (wrap === "auto") {
19+ try {
20+ return process.stdout.columns || 80;
21+ } catch {
22+ return 80;
23+ }
24+ }
25+ // wordWrap === 0 (disabled) – use a large value so visual-line count stays 1
26+ return Number.MAX_SAFE_INTEGER;
27+}
28+
1529 function resolveTheme(options?: Options): Theme {
1630 const t = options?.theme || "16";
1731 if (typeof t === "string") {
@@ -28,6 +42,7 @@ export function highlightSync(input: string, options?: Options): string {
2842
2943 export function createHighlighter(options?: Options): Highlighter {
3044 const theme = resolveTheme(options);
45+ const terminalColumns = resolveColumns(options);
3146 let buffer = "";
3247 let inCodeBlock = false;
3348
@@ -127,14 +142,38 @@ export function createHighlighter(options?: Options): Highlighter {
127142 return parseInline(line);
128143 }
129144
130- let hasPartial = false;
145+ let previousPartialLineCount = 0;
131146
132- function redrawPartialPrefix(): string {
133- return hasPartial ? "\x1b8\x1b[J" : "";
147+ // Strip ANSI escapes to measure visible character width
148+ function visibleLength(s: string): number {
149+ // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape regex
150+ return s.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "").length;
134151 }
135152
136- function renderPartial(line: string, isPartial: boolean): string {
137- return `\x1b7${parseLine(line, isPartial)}`;
153+ // Count visual (wrapped) lines a rendered string occupies.
154+ function countVisualLines(rendered: string): number {
155+ const len = visibleLength(rendered);
156+ if (len === 0) return 1;
157+ return Math.ceil(len / terminalColumns);
158+ }
159+
160+ // Erase the previous partial render using the standard eraseLines
161+ // pattern (same as log-update / ansi-escapes). All movement is
162+ // relative so it is immune to terminal scroll, unlike DECSC/DECRC.
163+ //
164+ // eraseLines(n) = for each line: eraseLine + cursorUp, then cursorLeft
165+ // eraseLine = \x1b[2K (erase entire line)
166+ // cursorUp = \x1b[1A
167+ // cursorLeft = \x1b[G (move to column 1)
168+ function eraseLines(count: number): string {
169+ if (count <= 0) return "";
170+ let seq = "";
171+ for (let i = 0; i < count; i++) {
172+ seq += "\x1b[2K"; // erase entire current line
173+ if (i < count - 1) seq += "\x1b[1A"; // move up (skip on last)
174+ }
175+ seq += "\x1b[G"; // move cursor to column 1
176+ return seq;
138177 }
139178
140179 return {
@@ -146,17 +185,18 @@ export function createHighlighter(options?: Options): Highlighter {
146185 const lines = buffer.split("\n");
147186 buffer = lines.pop() ?? "";
148187
149- let out = redrawPartialPrefix();
188+ let out = eraseLines(previousPartialLineCount);
150189
151190 if (lines.length > 0) {
152191 out += `${lines.map((line) => parseLine(line, false)).join("\n")}\n`;
153192 }
154193
155194 if (buffer.length > 0) {
156- out += renderPartial(buffer, true);
157- hasPartial = true;
195+ const rendered = parseLine(buffer, true);
196+ out += rendered;
197+ previousPartialLineCount = countVisualLines(rendered);
158198 } else {
159- hasPartial = false;
199+ previousPartialLineCount = 0;
160200 }
161201
162202 return out;
@@ -165,10 +205,10 @@ export function createHighlighter(options?: Options): Highlighter {
165205 if (buffer.length > 0) {
166206 const out = parseLine(buffer, false);
167207 buffer = "";
168- if (hasPartial) {
169- const redrawPrefix = redrawPartialPrefix();
170- hasPartial = false;
171- return redrawPrefix + out;
208+ if (previousPartialLineCount > 0) {
209+ const prefix = eraseLines(previousPartialLineCount);
210+ previousPartialLineCount = 0;
211+ return prefix + out;
172212 }
173213 return out;
174214 }
tests/index.test.ts+57−41
@@ -39,8 +39,6 @@ function renderTerminalOutput(
3939 const screen: string[][] = [[]];
4040 let row = 0;
4141 let column = 0;
42- let savedCursor: { row: number; column: number } | null = null;
43-
4442 function ensureRow(targetRow: number) {
4543 while (screen.length <= targetRow) {
4644 screen.push([]);
@@ -68,42 +66,58 @@ function renderTerminalOutput(
6866 for (let i = 0; i < output.length; i += 1) {
6967 const rest = output.slice(i);
7068
71- if (rest.startsWith("\x1b7")) {
72- savedCursor = { row, column };
73- i += 1;
74- continue;
75- }
76-
77- if (rest.startsWith("\x1b8")) {
78- if (savedCursor) {
79- row = savedCursor.row;
80- column = savedCursor.column;
81- }
82- i += 1;
83- continue;
84- }
85-
86- if (rest.startsWith("\x1b[J")) {
87- ensureRow(row);
88- screen[row] = (screen[row] ?? []).slice(0, column);
89- for (let clearRow = row + 1; clearRow < screen.length; clearRow += 1) {
90- screen[clearRow] = [];
69+ // Parse CSI sequences: \x1b[ <params> <letter>
70+ if (rest.startsWith("\x1b[")) {
71+ // biome-ignore lint/suspicious/noControlCharactersInRegex: ANSI escape regex
72+ const csiMatch = rest.match(/^\x1b\[([0-9;]*)([A-Za-z])/);
73+ if (csiMatch) {
74+ const param = csiMatch[1] ?? "";
75+ const code = csiMatch[2] ?? "";
76+ const n = param === "" ? 1 : parseInt(param, 10);
77+ i += csiMatch[0].length - 1; // -1 because loop does i++
78+
79+ switch (code) {
80+ case "A": // Cursor Up
81+ row = Math.max(0, row - n);
82+ break;
83+ case "D": // Cursor Backward
84+ column = Math.max(0, column - n);
85+ break;
86+ case "J": // Erase in Display (from cursor down)
87+ ensureRow(row);
88+ screen[row] = (screen[row] ?? []).slice(0, column);
89+ for (
90+ let clearRow = row + 1;
91+ clearRow < screen.length;
92+ clearRow += 1
93+ ) {
94+ screen[clearRow] = [];
95+ }
96+ break;
97+ case "K": {
98+ // Erase in Line
99+ const mode = param === "" ? 0 : n;
100+ ensureRow(row);
101+ if (mode === 0) {
102+ // erase to end of line
103+ screen[row] = (screen[row] ?? []).slice(0, column);
104+ } else if (mode === 2) {
105+ // erase whole line
106+ screen[row] = [];
107+ }
108+ break;
109+ }
110+ case "C": // Cursor Forward
111+ column += n;
112+ break;
113+ case "G": // Cursor Horizontal Absolute (1-based)
114+ column = (param === "" ? 1 : n) - 1;
115+ break;
116+ default:
117+ break;
118+ }
119+ continue;
91120 }
92- i += 2;
93- continue;
94- }
95-
96- if (rest.startsWith("\x1b[2K")) {
97- ensureRow(row);
98- screen[row] = [];
99- i += 3;
100- continue;
101- }
102-
103- if (rest.startsWith("\x1b[1A")) {
104- row = Math.max(0, row - 1);
105- i += 3;
106- continue;
107121 }
108122
109123 const char = output[i];
@@ -179,20 +193,22 @@ describe("Programmatic Usage: createHighlighter (Streaming)", () => {
179193 expectStreamMatch(res, markdown);
180194 });
181195
182- test("should redraw wrapped partial lines after an external prefix", () => {
183- const prefix = "◆ ";
196+ test("should erase and redraw partial lines that wrap in terminal", () => {
197+ // eraseLines uses \x1b[2K (erase whole line) + \x1b[1A (cursor up) +
198+ // \x1b[G (cursor to col 1) — the standard log-update / ansi-escapes
199+ // pattern. This is scroll-safe (all relative) unlike DECSC/DECRC.
184200 const markdown =
185201 "No `\\x1b[2K` or `\\r` sequences in the streamed text. The ANSI colour codes remain (intentional — those are static style codes from yoctocolors, not cursor-control sequences).\n";
186202 const splitAt = 134;
187203
188204 const highlighter = createHighlighter({ theme: "none" });
189- let res = prefix;
205+ let res = "";
190206 res += highlighter.write(markdown.slice(0, splitAt));
191207 res += highlighter.write(markdown.slice(splitAt));
192208 res += highlighter.end();
193209
194210 expect(renderTerminalOutput(res, 120)).toBe(
195- renderTerminalOutput(`${prefix}${markdown}`, 120),
211+ renderTerminalOutput(markdown, 120),
196212 );
197213 });
198214 });