vterm.js 0.6.1 → 0.7.0

package/README.md

@@ -435,6 +435,67 @@ The **reactive** counterpart is `signals.damage$` (see [Signals](#signals--the-r
 
 **Use vterm.js** when you need everything — 100% coverage of the [terminfo.dev](https://terminfo.dev) feature matrix.
 
+## vterm.js and xterm.js
+
+[xterm.js](https://www.npmjs.com/package/@xterm/xterm) is the standard for putting a terminal on a web page — DOM, canvas, and WebGL renderers, a large addon ecosystem, and the terminal inside VS Code. When the job is rendering a terminal to a human, reach for xterm.js. We do: [Termless](https://termless.dev)'s own `@termless/web-player`, which plays back recorded terminal sessions in the browser, is built directly on `@xterm/xterm`.
+
+vterm.js is for the opposite case: nothing ever gets painted. It's headless-first — the terminal as a **readable data structure**, not a rendered surface. Zero dependencies, pure TypeScript, full VT/ECMA-48/xterm standards coverage, a binary snapshot codec for exact state capture, a reactive read plane (`screen.signals`), absolute-row scrollback addressing, and semantic-zone detection (OSC 133 / OSC 633 prompt/command/output). That combination is aimed at testing, session recording, audit trails, and AI-agent infrastructure — consumers that need to know exactly what a terminal contains without ever drawing it.
+
+Because vterm.js makes no display claims, it's held to a stricter standard instead: engine conformance, graded publicly and continuously in [Termless](https://termless.dev)'s differential conformance corpus against xterm.js, Ghostty, and neovim's libvterm. Current per-engine results and every known gap live in the ratchet ledger (`known-gaps.json`) — it's two-way: an unlisted failure fails the build, and a listed gap that starts passing fails too. Full results are public at [termless.dev/advanced/conformance-corpus](https://termless.dev/advanced/conformance-corpus).
+
+## Deliberate divergences
+
+A handful of behaviours where vterm.js knowingly differs from neovim's
+libvterm, the reference implementation the conformance corpus is mined from.
+Each was ruled deliberately rather than left as a gap, so **100% conformance
+for vterm.js means 126/128 plus these documented divergences** — not 128.
+
+Each entry names the _override word_ that would reverse the ruling. If you need
+the other behaviour, open an issue with that word and the reason; it is the
+argument, not the preference, that would move it.
+
+### Cursor follows reflow when a resize shrinks below it
+
+Shrinking the terminal past the cursor's column carries the cursor with its
+line through the rewrap. libvterm, xterm.js and vt100.js instead clamp it to
+the last column of the row it was on.
+
+Following the line is what a reflowing terminal does — the cursor stays with
+the text a user was typing, rather than jumping to wherever that text used to
+end. Clamping is the pre-reflow behaviour the other three inherit from a
+shared ancestry, and three engines agreeing about their own history is not an
+argument about which is correct. Both ends of our own record/replay path read
+vterm.js, so there is no internal disagreement to resolve.
+
+**Override word: `clamp`.**
+
+### RIS clears the scrollback
+
+A full reset (`ESC c`) discards scrollback along with the screen. libvterm
+preserves it, so history banked before a reset can still be scrolled back to —
+and can even be popped back onto the screen by a later resize.
+
+Every other engine in the corpus — xterm.js, Ghostty and vt100.js — clears on
+RIS, as does xterm itself. A reset that leaves history behind surprises the
+common case, where `reset` is reached for precisely to get a clean terminal.
+
+**Override word: `match-ris`.**
+
+### Related: the deferred-wrap cursor
+
+Not an excluded case, but the same family and worth knowing if you read the
+cursor. When a glyph fills the last column with autowrap on, the terminal owes
+a wrap it has not performed. vterm.js represents that as the cursor sitting at
+`col == cols` — one past the last column — as xterm.js and vt100.js do.
+libvterm and Ghostty instead keep the cursor _on_ the last column and carry a
+separate pending-wrap flag. The corpus normalizes this rather than excluding
+it, so those cases pass; consumers reading `cursor.col` should simply expect
+the `col == cols` form.
+
+These entries mirror the corpus-side table in the suite's own README and the
+machine-readable reasons in `known-gaps.json`. A new ruling lands in all three
+at once.
+
 ## See also
 
 - [vt100.js](../vt100/) — VT100-era emulator (smaller, focused)

package/dist/index.d.mts

@@ -77,6 +77,8 @@ interface ScreenCell {
   hidden: boolean;
   blink: boolean;
   wide: boolean;
+  /** DECSCA: a selective erase (DECSED/DECSEL) leaves this cell alone. */
+  protected: boolean;
   url: string | null;
 }
 interface ScreenOptions {
@@ -118,6 +120,8 @@ interface ScreenAttrsSnapshot {
   inverse: boolean;
   hidden: boolean;
   blink: boolean;
+  /** DECSCA — cells written under it resist selective erase. */
+  protected: boolean;
   url: string | null;
 }
 interface ScreenColorStateSnapshot {
@@ -164,6 +168,26 @@ interface Snapshot {
    * `restore()` treats missing as all-false (hard-wrapped).
    */
   scrollbackSoftWrapped: boolean[];
+  /**
+   * DEC line attributes (DECDWL/DECDHL), SPARSE: only rows that are not normal
+   * appear, as `[rowIndex, attr]` pairs — 1 double-width, 2 double-height top,
+   * 3 double-height bottom.
+   *
+   * Sparse and header-resident on purpose. Double-width lines are a banner
+   * feature that almost no session emits, so a dense array per grid would be
+   * thousands of zeros; and the binary grid sections have no skippable framing,
+   * so a new array THERE would desynchronise an older reader rather than be
+   * ignored by it.
+   *
+   * Absent in snapshots taken before this field existed — `restore()` treats
+   * missing as all-normal. **Readers older than this field render DWL/DHL lines
+   * single-width**: a visual downgrade, never corruption.
+   */
+  lineAttrs?: {
+    main: [number, number][];
+    alt: [number, number][];
+    scrollback: [number, number][];
+  };
   cursor: {
     x: number;
     y: number;
@@ -193,6 +217,8 @@ interface Snapshot {
     focusTracking: boolean;
     origin: boolean;
     insert: boolean;
+    /** LNM — LF also returns the carriage. Absent in older snapshots. */
+    newLine: boolean;
     reverseVideo: boolean;
     syncOutput: boolean;
     kittyKeyboardFlags: number;
@@ -402,6 +428,8 @@ interface TerminalModes {
   focusTracking: boolean;
   originMode: boolean;
   insertMode: boolean;
+  /** LNM — LF also returns the carriage (ECMA-48 mode 20). */
+  newLineMode: boolean;
   reverseVideo: boolean;
   syncOutput: boolean;
   leftRightMargin: boolean;

package/dist/index.mjs

@@ -17,6 +17,7 @@ const EMPTY_CELL = Object.freeze({
 	hidden: false,
 	blink: false,
 	wide: false,
+	protected: false,
 	url: null
 });
 function emptyCell() {
@@ -31,7 +32,7 @@ function emptyCell() {
 * case), so the read path allocates nothing there.
 */
 function stripColorIndex(c) {
-	if (c === null || c.index === void 0) return c;
+	if (c?.index === void 0) return c;
 	return {
 		r: c.r,
 		g: c.g,
@@ -62,6 +63,7 @@ const F_HAS_FG = 4096;
 const F_HAS_BG = 8192;
 const F_HAS_UL = 16384;
 const F_HAS_URL = 32768;
+const F_PROTECTED$1 = 65536;
 const UL_STYLES = [
 	"none",
 	"single",
@@ -147,6 +149,7 @@ function makePackedRow(width) {
 		if (a.inverse) m |= F_INVERSE$1;
 		if (a.hidden) m |= F_HIDDEN$1;
 		if (a.blink) m |= F_BLINK$1;
+		if (a.protected) m |= F_PROTECTED$1;
 		if (wide) m |= F_WIDE$1;
 		return m | underlineToBits(a.underline);
 	}
@@ -234,6 +237,7 @@ function makePackedRow(width) {
 				inverse: (m & F_INVERSE$1) !== 0,
 				hidden: (m & F_HIDDEN$1) !== 0,
 				blink: (m & F_BLINK$1) !== 0,
+				protected: (m & F_PROTECTED$1) !== 0,
 				wide: (m & F_WIDE$1) !== 0,
 				url: m & F_HAS_URL ? urlMap.get(col) ?? null : null
 			};
@@ -497,6 +501,7 @@ function createScreen(options = {}) {
 	let focusTracking = false;
 	let originMode = false;
 	let insertMode = false;
+	let newLineMode = false;
 	let reverseVideo = false;
 	let syncOutput = false;
 	let kittyKeyboardFlags = 0;
@@ -778,7 +783,68 @@ function createScreen(options = {}) {
 	let mainSoftWrapped = new Array(rows).fill(false);
 	let altSoftWrapped = new Array(rows).fill(false);
 	let softWrapped = mainSoftWrapped;
+	let mainLineAttrs = new Array(rows).fill(0);
+	let altLineAttrs = new Array(rows).fill(0);
+	let lineAttrs = mainLineAttrs;
 	let scrollbackSoftWrapped = [];
+	let scrollbackLineAttrs = [];
+	/**
+	* Drop every banked scrollback row AND its soft-wrap flag.
+	*
+	* These two arrays are one data structure wearing two names, and nothing in
+	* the type system says so. `ESC [ 3 J` (erase display + scrollback) once
+	* emptied the rows and left the flags, which diverged the pair permanently
+	* by however many rows were banked at that instant. Every later push
+	* extended both and preserved the gap, so the snapshot codec refused to
+	* write a frame — `soft-wrap length 3580 != rowCount 2103` — and the seat
+	* kept running with its recording silently ended
+	* (@i/5-agent-loop/vterm-codec-ends-recording).
+	*
+	* `ESC [ 3 J` is not exotic: `clear` emits it on a modern terminal. Every
+	* clear goes through here so the pairing is structural rather than
+	* remembered at each call site.
+	*/
+	/** Dense per-row attributes -> sparse `[row, attr]` pairs, skipping normal rows. */
+	function toSparseAttrs(dense) {
+		const out = [];
+		for (let r = 0; r < dense.length; r++) {
+			const a = dense[r] ?? 0;
+			if (a !== 0) out.push([r, a]);
+		}
+		return out;
+	}
+	/** Sparse pairs -> a dense array of `length`; out-of-range rows are dropped. */
+	function fromSparseAttrs(sparse, length) {
+		const dense = new Array(length).fill(0);
+		for (const pair of sparse ?? []) {
+			const [r, a] = pair;
+			if (Number.isInteger(r) && r >= 0 && r < length) dense[r] = a;
+		}
+		return dense;
+	}
+	function clearScrollback() {
+		scrollback.length = 0;
+		scrollbackSoftWrapped.length = 0;
+		scrollbackLineAttrs.length = 0;
+	}
+	/**
+	* Bank one row into scrollback, trimming to the limit. Returns how many rows
+	* were trimmed off the front so a caller tracking absolute rows can rebase.
+	*
+	* Every scrollback mutation goes through a helper that moves BOTH arrays —
+	* see `clearScrollback` for what one unpaired mutation cost.
+	*/
+	function bankScrollbackRow(row, wrapped, lineAttr) {
+		scrollback.push(row);
+		scrollbackSoftWrapped.push(wrapped);
+		scrollbackLineAttrs.push(lineAttr);
+		if (scrollback.length <= scrollbackLimit * 2) return 0;
+		const over = scrollback.length - scrollbackLimit;
+		scrollback.splice(0, over);
+		scrollbackSoftWrapped.splice(0, over);
+		scrollbackLineAttrs.splice(0, over);
+		return over;
+	}
 	let lastChar = "";
 	let pendingRegionalIndicator = null;
 	let afterZWJ = false;
@@ -912,6 +978,16 @@ function createScreen(options = {}) {
 		fn(cells);
 		row.replaceAllFromCells(cells);
 	}
+	/**
+	* SGR 0 resets the pen but NOT DECSCA: character protection is independent
+	* of SGR, and is cleared only by DECSTR/RIS. Using the full `resetAttrs()`
+	* here would let any `ESC [ 0 m` silently unprotect subsequent writes.
+	*/
+	function resetSgrAttrs() {
+		const next = resetAttrs();
+		next.protected = attrs.protected;
+		return next;
+	}
 	function resetAttrs() {
 		return {
 			fg: null,
@@ -926,14 +1002,49 @@ function createScreen(options = {}) {
 			inverse: false,
 			hidden: false,
 			blink: false,
-			url: null
+			url: null,
+			protected: false
 		};
 	}
+	/**
+	* Usable columns on a row. A DEC double-width line (DECDWL/DECDHL) renders
+	* each cell twice as wide, so the row addresses and wraps at half the
+	* terminal's columns — an 80-column screen wraps a double-width line at 40.
+	*/
+	function rowCols(row) {
+		return (lineAttrs[row] ?? 0) === 0 ? cols : cols >> 1;
+	}
 	function clampCursor() {
 		if (curX < 0) curX = 0;
-		if (curX >= cols) curX = cols - 1;
 		if (curY < 0) curY = 0;
 		if (curY >= rows) curY = rows - 1;
+		const usable = rowCols(curY);
+		if (curX >= usable) curX = usable - 1;
+		if (originMode) {
+			if (curY < scrollTop) curY = scrollTop;
+			if (curY > scrollBottom) curY = scrollBottom;
+		}
+	}
+	/**
+	* Move the cursor down one line, scrolling ONLY at the region's bottom edge.
+	*
+	* `curY++; if (curY > scrollBottom) { curY = scrollBottom; scrollUp() }`
+	* looks equivalent and is not. From a row BELOW the scrolling region it
+	* clamps the cursor BACKWARDS into the region and scrolls a region the
+	* cursor was never in — with DECSTBM at 1;10, a linefeed from row 19 landed
+	* on row 9 instead of row 20.
+	*
+	* DECSTBM confines SCROLLING, not movement: a cursor outside the region
+	* simply walks the screen.
+	*/
+	function lineFeedDown() {
+		if (curY === scrollBottom) scrollUp(scrollTop, scrollBottom);
+		else if (curY < rows - 1) curY++;
+	}
+	/** RI's mirror: scroll only at the region's top edge, else walk up. */
+	function reverseIndexUp() {
+		if (curY === scrollTop) scrollDown(scrollTop, scrollBottom);
+		else if (curY > 0) curY--;
 	}
 	function scrollUp(top, bottom) {
 		if (leftRightMarginMode && (leftMargin > 0 || rightMargin < cols - 1)) {
@@ -950,13 +1061,10 @@ function createScreen(options = {}) {
 		} else {
 			const enteredScrollback = grid === mainGrid && top === 0;
 			if (enteredScrollback) {
-				scrollback.push(grid[0]);
-				scrollbackSoftWrapped.push(softWrapped[0] ?? false);
-				markAbsoluteRowDirty(scrollback.length - 1);
-				if (scrollback.length > scrollbackLimit * 2) {
-					const over = scrollback.length - scrollbackLimit;
-					scrollback.splice(0, over);
-					scrollbackSoftWrapped.splice(0, over);
+				const banked = grid[0];
+				const over = banked === void 0 ? 0 : bankScrollbackRow(banked, softWrapped[0] ?? false, lineAttrs[0] ?? 0);
+				markAbsoluteRowDirty(scrollback.length - 1 + over);
+				if (over > 0) {
 					if (!dirtyAll && dirtyRows.size > 0) {
 						const shifted = /* @__PURE__ */ new Set();
 						for (const r of dirtyRows) if (r >= over) shifted.add(r - over);
@@ -1108,7 +1216,7 @@ function createScreen(options = {}) {
 	function writeCharCore(ch, wide) {
 		if (cols <= 0 || rows <= 0) return;
 		const charWidth = wide ? 2 : 1;
-		const wrapBoundary = leftRightMarginMode ? rightMargin + 1 : cols;
+		const wrapBoundary = leftRightMarginMode ? rightMargin + 1 : rowCols(curY);
 		const wrapReturn = leftRightMarginMode ? leftMargin : 0;
 		if (curX + charWidth > wrapBoundary) if (autoWrap) {
 			softWrapped[curY] = true;
@@ -1133,6 +1241,7 @@ function createScreen(options = {}) {
 		if (wide) widenCell(row, curX);
 		markScreenRowDirty(curY);
 		curX += charWidth;
+		if (!autoWrap && curX >= wrapBoundary) curX = wrapBoundary - 1;
 		lastChar = ch;
 	}
 	function handleCSI(params, intermediates, finalByte) {
@@ -1169,6 +1278,10 @@ function createScreen(options = {}) {
 			else if (finalByte === "A") handleShiftRight(Math.max(parts[0] ?? 1, 1));
 			return;
 		}
+		if (intermediates === "\"" && finalByte === "q") {
+			attrs.protected = (parts[0] ?? 0) === 1;
+			return;
+		}
 		if (intermediates === "!") {
 			if (finalByte === "p") softReset();
 			return;
@@ -1278,18 +1391,22 @@ function createScreen(options = {}) {
 		}
 		switch (finalByte) {
 			case "A":
+			case "k":
 				curY -= Math.max(parts[0] ?? 1, 1);
 				clampCursor();
 				break;
 			case "B":
+			case "e":
 				curY += Math.max(parts[0] ?? 1, 1);
 				clampCursor();
 				break;
 			case "C":
+			case "a":
 				curX += Math.max(parts[0] ?? 1, 1);
 				clampCursor();
 				break;
 			case "D":
+			case "j":
 				curX -= Math.max(parts[0] ?? 1, 1);
 				clampCursor();
 				break;
@@ -1351,12 +1468,14 @@ function createScreen(options = {}) {
 			case "H":
 			case "f":
 				if (originMode) {
+					const originX = leftRightMarginMode ? leftMargin : 0;
+					const limitX = leftRightMarginMode ? rightMargin : cols - 1;
 					curY = scrollTop + (parts[0] ?? 1) - 1;
-					curX = (parts[1] ?? 1) - 1;
+					curX = originX + (parts[1] ?? 1) - 1;
 					if (curY < scrollTop) curY = scrollTop;
 					if (curY > scrollBottom) curY = scrollBottom;
-					if (curX < 0) curX = 0;
-					if (curX >= cols) curX = cols - 1;
+					if (curX < originX) curX = originX;
+					if (curX > limitX) curX = limitX;
 				} else {
 					curY = (parts[0] ?? 1) - 1;
 					curX = (parts[1] ?? 1) - 1;
@@ -1427,10 +1546,16 @@ function createScreen(options = {}) {
 				}
 				break;
 			case "h":
-				for (const code of parts) if (code === 4) insertMode = true;
+				for (const code of parts) {
+					if (code === 4) insertMode = true;
+					if (code === 20) newLineMode = true;
+				}
 				break;
 			case "l":
-				for (const code of parts) if (code === 4) insertMode = false;
+				for (const code of parts) {
+					if (code === 4) insertMode = false;
+					if (code === 20) newLineMode = false;
+				}
 				break;
 			case "s":
 				if (leftRightMarginMode && intermediates === "") {
@@ -1551,6 +1676,9 @@ function createScreen(options = {}) {
 					case 4:
 						value = insertMode ? 1 : 2;
 						break;
+					case 20:
+						value = newLineMode ? 1 : 2;
+						break;
 					case 3:
 						value = decColumnMode ? 1 : 2;
 						break;
@@ -1577,11 +1705,11 @@ function createScreen(options = {}) {
 			return;
 		}
 		if (finalByte === "J") {
-			handleEraseDisplay(parts[0] ?? 0);
+			handleEraseDisplay(parts[0] ?? 0, true);
 			return;
 		}
 		if (finalByte === "K") {
-			handleEraseLine(parts[0] ?? 0);
+			handleEraseLine(parts[0] ?? 0, true);
 			return;
 		}
 		const set = finalByte === "h";
@@ -1610,11 +1738,13 @@ function createScreen(options = {}) {
 					useAltScreen = true;
 					grid = altGrid;
 					softWrapped = altSoftWrapped;
+					lineAttrs = altLineAttrs;
 					markAllDirty();
 				} else if (!set && useAltScreen) {
 					useAltScreen = false;
 					grid = mainGrid;
 					softWrapped = mainSoftWrapped;
+					lineAttrs = mainLineAttrs;
 					markAllDirty();
 				}
 				break;
@@ -1643,8 +1773,10 @@ function createScreen(options = {}) {
 					useAltScreen = true;
 					altGrid = makeGrid(cols, rows);
 					altSoftWrapped = new Array(rows).fill(false);
+					altLineAttrs = new Array(rows).fill(0);
 					grid = altGrid;
 					softWrapped = altSoftWrapped;
+					lineAttrs = altLineAttrs;
 					curX = 0;
 					curY = 0;
 					markAllDirty();
@@ -1652,6 +1784,7 @@ function createScreen(options = {}) {
 					useAltScreen = false;
 					grid = mainGrid;
 					softWrapped = mainSoftWrapped;
+					lineAttrs = mainLineAttrs;
 					curX = savedCurX;
 					curY = savedCurY;
 					clampCursor();
@@ -1698,43 +1831,46 @@ function createScreen(options = {}) {
 				break;
 		}
 	}
-	function handleEraseDisplay(mode) {
+	function handleEraseDisplay(mode, selective = false) {
 		switch (mode) {
 			case 0:
-				eraseCells(curY, curX, curY, cols - 1);
-				for (let row = curY + 1; row < rows; row++) eraseCells(row, 0, row, cols - 1);
+				eraseCells(curY, curX, curY, cols - 1, selective);
+				for (let row = curY + 1; row < rows; row++) eraseCells(row, 0, row, cols - 1, selective);
 				break;
 			case 1:
-				for (let row = 0; row < curY; row++) eraseCells(row, 0, row, cols - 1);
-				eraseCells(curY, 0, curY, curX);
+				for (let row = 0; row < curY; row++) eraseCells(row, 0, row, cols - 1, selective);
+				eraseCells(curY, 0, curY, curX, selective);
 				break;
 			case 2:
 			case 3:
-				for (let row = 0; row < rows; row++) eraseCells(row, 0, row, cols - 1);
-				if (mode === 3) scrollback.length = 0;
+				for (let row = 0; row < rows; row++) eraseCells(row, 0, row, cols - 1, selective);
+				if (mode === 3) clearScrollback();
 				markAllDirty();
 				break;
 		}
 	}
-	function handleEraseLine(mode) {
+	function handleEraseLine(mode, selective = false) {
 		const eraseRight = leftRightMarginMode ? rightMargin : cols - 1;
 		const eraseLeft = leftRightMarginMode ? leftMargin : 0;
 		switch (mode) {
 			case 0:
-				eraseCells(curY, curX, curY, eraseRight);
+				eraseCells(curY, curX, curY, eraseRight, selective);
 				break;
 			case 1:
-				eraseCells(curY, eraseLeft, curY, curX);
+				eraseCells(curY, eraseLeft, curY, curX, selective);
 				break;
 			case 2:
-				eraseCells(curY, eraseLeft, curY, eraseRight);
+				eraseCells(curY, eraseLeft, curY, eraseRight, selective);
 				break;
 		}
 	}
-	function eraseCells(row, startCol, _endRow, endCol) {
+	function eraseCells(row, startCol, _endRow, endCol, selective = false) {
 		const r = grid[row];
 		if (!r) return;
-		for (let col = startCol; col <= endCol && col < cols; col++) r.eraseWithBg(col, attrs.bg);
+		for (let col = startCol; col <= endCol && col < cols; col++) {
+			if (selective && r.getCellRaw(col).protected) continue;
+			r.eraseWithBg(col, attrs.bg);
+		}
 		markScreenRowDirty(row);
 	}
 	function handleInsertLines(count) {
@@ -1893,7 +2029,7 @@ function createScreen(options = {}) {
 			params.push(subs[0]);
 		} else params.push(seg === "" ? 0 : parseInt(seg, 10));
 		if (params.length === 0 || params.length === 1 && params[0] === 0) {
-			attrs = resetAttrs();
+			attrs = resetSgrAttrs();
 			return;
 		}
 		let i = 0;
@@ -1901,7 +2037,7 @@ function createScreen(options = {}) {
 			const code = params[i];
 			switch (code) {
 				case 0:
-					attrs = resetAttrs();
+					attrs = resetSgrAttrs();
 					break;
 				case 1:
 					attrs.bold = true;
@@ -2602,6 +2738,7 @@ function createScreen(options = {}) {
 	}
 	function softReset() {
 		insertMode = false;
+		newLineMode = false;
 		originMode = false;
 		autoWrap = true;
 		curVisible = true;
@@ -2659,6 +2796,7 @@ function createScreen(options = {}) {
 		focusTracking = false;
 		originMode = false;
 		insertMode = false;
+		newLineMode = false;
 		reverseVideo = false;
 		syncOutput = false;
 		kittyKeyboardFlags = 0;
@@ -2717,6 +2855,9 @@ function createScreen(options = {}) {
 		mainSoftWrapped = new Array(rows).fill(false);
 		altSoftWrapped = new Array(rows).fill(false);
 		softWrapped = mainSoftWrapped;
+		mainLineAttrs = new Array(rows).fill(0);
+		altLineAttrs = new Array(rows).fill(0);
+		lineAttrs = mainLineAttrs;
 		markAllDirty();
 		dirtyScrolled = 0;
 		if (sigDamageActive) sigDirtyScrolled = 0;
@@ -2868,11 +3009,8 @@ function createScreen(options = {}) {
 						emitExecute(9);
 					} else if (code === 10 || code === 11 || code === 12) {
 						softWrapped[curY] = false;
-						curY++;
-						if (curY > scrollBottom) {
-							curY = scrollBottom;
-							scrollUp(scrollTop, scrollBottom);
-						}
+						lineFeedDown();
+						if (newLineMode) curX = 0;
 						emitExecute(code);
 					} else if (code === 13) {
 						curX = 0;
@@ -2910,19 +3048,11 @@ function createScreen(options = {}) {
 						parserState = "ground";
 						emitEsc("c", "");
 					} else if (ch === "D") {
-						curY++;
-						if (curY > scrollBottom) {
-							curY = scrollBottom;
-							scrollUp(scrollTop, scrollBottom);
-						}
+						lineFeedDown();
 						parserState = "ground";
 						emitEsc("D", "");
 					} else if (ch === "M") {
-						curY--;
-						if (curY < scrollTop) {
-							curY = scrollTop;
-							scrollDown(scrollTop, scrollBottom);
-						}
+						reverseIndexUp();
 						parserState = "ground";
 						emitEsc("M", "");
 					} else if (ch === "7") {
@@ -3012,7 +3142,10 @@ function createScreen(options = {}) {
 						}
 						curX = 0;
 						curY = 0;
-					}
+					} else if (ch === "3") lineAttrs[curY] = 2;
+					else if (ch === "4") lineAttrs[curY] = 3;
+					else if (ch === "5") lineAttrs[curY] = 0;
+					else if (ch === "6") lineAttrs[curY] = 1;
 					parserState = "ground";
 					emitEsc(ch, escIntermediate);
 					break;
@@ -3129,9 +3262,25 @@ function createScreen(options = {}) {
 	* trailing blanks or one past the last cell) lands after the last emitted
 	* cell, advanced by the leftover distance, clamped to the row.
 	*/
+	/**
+	* One line attribute per LOGICAL line, taken from the line's FIRST physical
+	* row — the grouping `getLogicalLines` uses, so the two arrays line up.
+	* A rewrap then re-applies the attribute to every row the line becomes.
+	*/
+	function logicalLineAttrs(srcGrid, srcSoftWrapped, srcLineAttrs, srcRows) {
+		const out = [];
+		let starting = true;
+		for (let r = 0; r < srcRows; r++) {
+			if (!srcGrid[r]) continue;
+			if (starting) out.push(srcLineAttrs[r] ?? 0);
+			starting = !srcSoftWrapped[r];
+		}
+		return out;
+	}
 	function rewrapLines(logicalLines, newCols, track) {
 		const outRows = [];
 		const outWrapped = [];
+		const outLine = [];
 		let tracked = null;
 		for (let li = 0; li < logicalLines.length; li++) {
 			const line = logicalLines[li];
@@ -3144,7 +3293,8 @@ function createScreen(options = {}) {
 			if (lineLen === 0) {
 				outRows.push(makeRow(newCols));
 				outWrapped.push(false);
-				if (track !== void 0 && track.line === li) tracked = {
+				outLine.push(li);
+				if (track?.line === li) tracked = {
 					row: outRows.length - 1,
 					col: Math.min(track.offset, newCols - 1)
 				};
@@ -3157,7 +3307,7 @@ function createScreen(options = {}) {
 				while (col < newCols && pos < lineLen) {
 					const cell = line[pos];
 					if (cell.wide && col + 2 > newCols) break;
-					if (track !== void 0 && track.line === li && pos === track.offset) tracked = {
+					if (track?.line === li && pos === track.offset) tracked = {
 						row: outRows.length,
 						col
 					};
@@ -3168,7 +3318,8 @@ function createScreen(options = {}) {
 				const moreContent = pos < lineLen;
 				outRows.push(row);
 				outWrapped.push(moreContent);
-				if (!moreContent && track !== void 0 && track.line === li && tracked === null) {
+				outLine.push(li);
+				if (!moreContent && track?.line === li && tracked === null) {
 					const extra = track.offset - lineLen;
 					tracked = {
 						row: outRows.length - 1,
@@ -3180,6 +3331,7 @@ function createScreen(options = {}) {
 		return {
 			rows: outRows,
 			wrapped: outWrapped,
+			lineIndex: outLine,
 			tracked
 		};
 	}
@@ -3191,13 +3343,20 @@ function createScreen(options = {}) {
 	/**
 	* Trim trailing empty rows from reflowed result, so they don't push content off the top
 	* when we take the last newRows rows.
+	*
+	* Never trims the row the CURSOR is on. A shell that has just emitted its
+	* final newline sits on a blank last row, and dropping it makes the content
+	* measure one row shorter than it is — so a shrink banks one row too few and
+	* every surviving line lands one row low, taking the cursor with it.
 	*/
 	function trimTrailingEmptyRows(result) {
-		while (result.rows.length > 1) {
+		const floor = result.tracked == null ? 1 : Math.max(1, result.tracked.row + 1);
+		while (result.rows.length > floor) {
 			const lastRow = result.rows[result.rows.length - 1];
 			if (packedRowIsBlank(lastRow) && !result.wrapped[result.rows.length - 2]) {
 				result.rows.pop();
 				result.wrapped.pop();
+				result.lineIndex?.pop();
 			} else break;
 		}
 	}
@@ -3213,23 +3372,56 @@ function createScreen(options = {}) {
 			line: cursorLineIdx,
 			offset: (cursorRowPre - cursorLineStart) * cols + curX
 		};
-		const mainResult = rewrapLines(getLogicalLines(mainGrid, mainSoftWrapped, rows), newCols, useAltScreen ? void 0 : cursorTrack);
+		let restoredRows = [];
+		let restoredWrapped = [];
+		let restoredAttrs = [];
+		if (!useAltScreen && newRows > rows && scrollback.length > 0) {
+			const probe = rewrapLines(getLogicalLines(mainGrid, mainSoftWrapped, rows), newCols, void 0);
+			trimTrailingEmptyRows(probe);
+			const take = Math.min(Math.max(0, newRows - probe.rows.length), scrollback.length);
+			if (take > 0) {
+				restoredRows = scrollback.splice(scrollback.length - take, take);
+				restoredWrapped = scrollbackSoftWrapped.splice(scrollbackSoftWrapped.length - take, take);
+				restoredAttrs = scrollbackLineAttrs.splice(scrollbackLineAttrs.length - take, take);
+			}
+		}
+		if (restoredRows.length > 0) {
+			let completed = 0;
+			for (const wrapped of restoredWrapped) if (!wrapped) completed++;
+			if (cursorTrack.line === 0 && restoredWrapped[restoredWrapped.length - 1] === true) for (let i = restoredWrapped.length - 1; i >= 0 && restoredWrapped[i]; i--) cursorTrack.offset += restoredRows[i].length;
+			cursorTrack.line += completed;
+		}
+		const mainSrc = restoredRows.length > 0 ? [...restoredRows, ...mainGrid] : mainGrid;
+		const mainSrcWrapped = restoredRows.length > 0 ? [...restoredWrapped, ...mainSoftWrapped] : mainSoftWrapped;
+		const mainSrcAttrs = restoredRows.length > 0 ? [...restoredAttrs, ...mainLineAttrs] : mainLineAttrs;
+		const mainSrcRows = restoredRows.length + rows;
+		const mainLogicalAttrs = logicalLineAttrs(mainSrc, mainSrcWrapped, mainSrcAttrs, mainSrcRows);
+		const mainResult = rewrapLines(getLogicalLines(mainSrc, mainSrcWrapped, mainSrcRows), newCols, useAltScreen ? void 0 : cursorTrack);
 		trimTrailingEmptyRows(mainResult);
+		const altLogicalAttrs = logicalLineAttrs(altGrid, altSoftWrapped, altLineAttrs, rows);
 		const altResult = rewrapLines(getLogicalLines(altGrid, altSoftWrapped, rows), newCols, useAltScreen ? cursorTrack : void 0);
 		trimTrailingEmptyRows(altResult);
 		const newMain = makeGrid(newCols, newRows);
 		const newMainWrapped = new Array(newRows).fill(false);
+		const newMainAttrs = new Array(newRows).fill(0);
 		const mainStartRow = Math.max(0, mainResult.rows.length - newRows);
+		for (let r = 0; r < mainStartRow; r++) {
+			const overflow = mainResult.rows[r];
+			if (overflow !== void 0) bankScrollbackRow(overflow, mainResult.wrapped[r] ?? false, mainLogicalAttrs[mainResult.lineIndex[r] ?? 0] ?? 0);
+		}
 		for (let r = 0; r < newRows && mainStartRow + r < mainResult.rows.length; r++) {
 			newMain[r] = mainResult.rows[mainStartRow + r];
 			newMainWrapped[r] = mainResult.wrapped[mainStartRow + r];
+			newMainAttrs[r] = mainLogicalAttrs[mainResult.lineIndex[mainStartRow + r] ?? 0] ?? 0;
 		}
 		const newAlt = makeGrid(newCols, newRows);
 		const newAltWrapped = new Array(newRows).fill(false);
+		const newAltAttrs = new Array(newRows).fill(0);
 		const altStartRow = Math.max(0, altResult.rows.length - newRows);
 		for (let r = 0; r < newRows && altStartRow + r < altResult.rows.length; r++) {
 			newAlt[r] = altResult.rows[altStartRow + r];
 			newAltWrapped[r] = altResult.wrapped[altStartRow + r];
+			newAltAttrs[r] = altLogicalAttrs[altResult.lineIndex[altStartRow + r] ?? 0] ?? 0;
 		}
 		const activeResult = useAltScreen ? altResult : mainResult;
 		const activeStartRow = useAltScreen ? altStartRow : mainStartRow;
@@ -3241,8 +3433,11 @@ function createScreen(options = {}) {
 		altGrid = newAlt;
 		mainSoftWrapped = newMainWrapped;
 		altSoftWrapped = newAltWrapped;
+		mainLineAttrs = newMainAttrs;
+		altLineAttrs = newAltAttrs;
 		grid = useAltScreen ? altGrid : mainGrid;
 		softWrapped = useAltScreen ? altSoftWrapped : mainSoftWrapped;
+		lineAttrs = useAltScreen ? altLineAttrs : mainLineAttrs;
 		const oldCols = cols;
 		cols = newCols;
 		rows = newRows;
@@ -3277,6 +3472,11 @@ function createScreen(options = {}) {
 			},
 			scrollback: cloneGridSnapshot(scrollback),
 			scrollbackSoftWrapped: [...scrollbackSoftWrapped],
+			lineAttrs: {
+				main: toSparseAttrs(mainLineAttrs),
+				alt: toSparseAttrs(altLineAttrs),
+				scrollback: toSparseAttrs(scrollbackLineAttrs)
+			},
 			cursor: {
 				x: curX,
 				y: curY,
@@ -3306,6 +3506,7 @@ function createScreen(options = {}) {
 				focusTracking,
 				origin: originMode,
 				insert: insertMode,
+				newLine: newLineMode,
 				reverseVideo,
 				syncOutput,
 				kittyKeyboardFlags,
@@ -3372,9 +3573,13 @@ function createScreen(options = {}) {
 		scrollbackSoftWrapped = snapshotValue.scrollbackSoftWrapped ? [...snapshotValue.scrollbackSoftWrapped] : new Array(scrollback.length).fill(false);
 		mainSoftWrapped = [...snapshotValue.main.softWrapped];
 		altSoftWrapped = [...snapshotValue.alt.softWrapped];
+		mainLineAttrs = fromSparseAttrs(snapshotValue.lineAttrs?.main, mainSoftWrapped.length);
+		altLineAttrs = fromSparseAttrs(snapshotValue.lineAttrs?.alt, altSoftWrapped.length);
+		scrollbackLineAttrs = fromSparseAttrs(snapshotValue.lineAttrs?.scrollback, scrollback.length);
 		useAltScreen = snapshotValue.activeBuffer === "alt";
 		grid = useAltScreen ? altGrid : mainGrid;
 		softWrapped = useAltScreen ? altSoftWrapped : mainSoftWrapped;
+		lineAttrs = useAltScreen ? altLineAttrs : mainLineAttrs;
 		curX = snapshotValue.cursor.x;
 		curY = snapshotValue.cursor.y;
 		curVisible = snapshotValue.cursor.visible;
@@ -3401,6 +3606,7 @@ function createScreen(options = {}) {
 		focusTracking = snapshotValue.modes.focusTracking;
 		originMode = snapshotValue.modes.origin;
 		insertMode = snapshotValue.modes.insert;
+		newLineMode = snapshotValue.modes.newLine ?? false;
 		reverseVideo = snapshotValue.modes.reverseVideo;
 		syncOutput = snapshotValue.modes.syncOutput;
 		kittyKeyboardFlags = snapshotValue.modes.kittyKeyboardFlags;
@@ -3558,6 +3764,7 @@ function createScreen(options = {}) {
 			case "focusTracking": return focusTracking;
 			case "originMode": return originMode;
 			case "insertMode": return insertMode;
+			case "newLineMode": return newLineMode;
 			case "reverseVideo": return reverseVideo;
 			case "syncOutput": return syncOutput;
 			case "sgrMouse": return sgrMouse;
@@ -3637,6 +3844,7 @@ function createScreen(options = {}) {
 			focusTracking,
 			originMode,
 			insertMode,
+			newLineMode,
 			reverseVideo,
 			syncOutput,
 			leftRightMargin: leftRightMarginMode,
@@ -3647,7 +3855,7 @@ function createScreen(options = {}) {
 		};
 	}
 	function modesEq(a, b) {
-		return a.altScreen === b.altScreen && a.cursorVisible === b.cursorVisible && a.bracketedPaste === b.bracketedPaste && a.applicationCursor === b.applicationCursor && a.applicationKeypad === b.applicationKeypad && a.autoWrap === b.autoWrap && a.mouseTracking === b.mouseTracking && a.mouseTrackingMode === b.mouseTrackingMode && a.sgrMouse === b.sgrMouse && a.utf8Mouse === b.utf8Mouse && a.focusTracking === b.focusTracking && a.originMode === b.originMode && a.insertMode === b.insertMode && a.reverseVideo === b.reverseVideo && a.syncOutput === b.syncOutput && a.leftRightMargin === b.leftRightMargin && a.colorSchemeReporting === b.colorSchemeReporting && a.kittyKeyboard === b.kittyKeyboard && a.kittyGraphics === b.kittyGraphics && a.sixel === b.sixel;
+		return a.altScreen === b.altScreen && a.cursorVisible === b.cursorVisible && a.bracketedPaste === b.bracketedPaste && a.applicationCursor === b.applicationCursor && a.applicationKeypad === b.applicationKeypad && a.autoWrap === b.autoWrap && a.mouseTracking === b.mouseTracking && a.mouseTrackingMode === b.mouseTrackingMode && a.sgrMouse === b.sgrMouse && a.utf8Mouse === b.utf8Mouse && a.focusTracking === b.focusTracking && a.originMode === b.originMode && a.insertMode === b.insertMode && a.newLineMode === b.newLineMode && a.reverseVideo === b.reverseVideo && a.syncOutput === b.syncOutput && a.leftRightMargin === b.leftRightMargin && a.colorSchemeReporting === b.colorSchemeReporting && a.kittyKeyboard === b.kittyKeyboard && a.kittyGraphics === b.kittyGraphics && a.sixel === b.sixel;
 	}
 	const damageListeners = /* @__PURE__ */ new Set();
 	let damageLast = {
@@ -4112,10 +4320,12 @@ function serializeSnapshot(snapshot, options = {}) {
 	if (hyperlinks && snapshot.attrs.url !== null) out.push(`\x1b]8;;${snapshot.attrs.url}\x1b\\`);
 	out.push(snapshot.cursor.visible ? "\x1B[?25h" : "\x1B[?25l");
 	const origin = m.origin && !excluded.has("origin");
-	const inRegion = snapshot.cursor.y >= snapshot.margins.scrollTop && snapshot.cursor.y <= snapshot.margins.scrollBottom;
+	const originX = snapshot.margins.leftRight ? snapshot.margins.left : 0;
+	const limitX = snapshot.margins.leftRight ? snapshot.margins.right : snapshot.cols - 1;
+	const inRegion = snapshot.cursor.y >= snapshot.margins.scrollTop && snapshot.cursor.y <= snapshot.margins.scrollBottom && snapshot.cursor.x >= originX && snapshot.cursor.x <= limitX;
 	if (origin && inRegion) {
 		out.push("\x1B[?6h");
-		out.push(`\x1b[${String(snapshot.cursor.y - snapshot.margins.scrollTop + 1)};${String(snapshot.cursor.x + 1)}H`);
+		out.push(`\x1b[${String(snapshot.cursor.y - snapshot.margins.scrollTop + 1)};${String(snapshot.cursor.x - originX + 1)}H`);
 	} else {
 		out.push(`\x1b[${String(snapshot.cursor.y + 1)};${String(snapshot.cursor.x + 1)}H`);
 		if (origin) out.push("\x1B[?6h");
@@ -4138,6 +4348,7 @@ const F_BLINK = 128;
 const F_WIDE = 256;
 const UL_SHIFT = 9;
 const UL_MASK = 7;
+const F_PROTECTED = 65536;
 const UNDERLINE_STYLES = [
 	"none",
 	"single",
@@ -4368,6 +4579,7 @@ function createInterner() {
 		if (cell.inverse) flags |= F_INVERSE;
 		if (cell.hidden) flags |= F_HIDDEN;
 		if (cell.blink) flags |= F_BLINK;
+		if (cell.protected) flags |= F_PROTECTED;
 		if (cell.wide) flags |= F_WIDE;
 		flags |= ulIdx << UL_SHIFT;
 		const key = `${flags}|${fgRef}|${bgRef}|${ulRef}|${urlRef}`;
@@ -4536,6 +4748,7 @@ function makeCell(charIdx, styleIdx, strings, colors, styles) {
 		inverse: (style.flags & F_INVERSE) !== 0,
 		hidden: (style.flags & F_HIDDEN) !== 0,
 		blink: (style.flags & F_BLINK) !== 0,
+		protected: (style.flags & F_PROTECTED) !== 0,
 		wide: (style.flags & F_WIDE) !== 0,
 		url
 	};
@@ -4589,6 +4802,7 @@ function encodeScreenSnapshotBinary(snapshot) {
 		savedState: snapshot.savedState,
 		attrs: snapshot.attrs,
 		modes: snapshot.modes,
+		lineAttrs: snapshot.lineAttrs,
 		margins: snapshot.margins,
 		colors: snapshot.colors,
 		tabStops: snapshot.tabStops,
@@ -4656,6 +4870,7 @@ function decodeScreenSnapshotBinary(bytes) {
 		savedState: header.savedState,
 		attrs: header.attrs,
 		modes: header.modes,
+		lineAttrs: header.lineAttrs,
 		margins: header.margins,
 		colors: header.colors,
 		tabStops: header.tabStops,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vterm.js",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Modern terminal emulator — full VT/ECMA-48/xterm standards coverage. Pure TypeScript, zero dependencies.",
   "keywords": [
     "ansi",