vterm.js 0.4.0 → 0.5.1

package/dist/index.mjs

@@ -20,6 +20,248 @@ const EMPTY_CELL = Object.freeze({
 function emptyCell() {
 	return { ...EMPTY_CELL };
 }
+/**
+* Drop the palette-origin {@link CellColor.index} for the public per-cell read
+* boundary. `getCell`/`getLine` return the RESOLVED RGB — their long-standing
+* contract — while the origin index is serialization-only provenance that rides
+* {@link ScreenSnapshot} (and thus `serialize()`), not the inspection API.
+* Returns the SAME reference when there is no index (the common truecolor/null
+* case), so the read path allocates nothing there.
+*/
+function stripColorIndex(c) {
+	if (c === null || c.index === void 0) return c;
+	return {
+		r: c.r,
+		g: c.g,
+		b: c.b
+	};
+}
+/** Shallow cell copy with each color stripped of its palette-origin index. */
+function stripCellColorIndex(cell) {
+	return {
+		...cell,
+		fg: stripColorIndex(cell.fg),
+		bg: stripColorIndex(cell.bg),
+		underlineColor: stripColorIndex(cell.underlineColor)
+	};
+}
+const F_BOLD$1 = 1;
+const F_FAINT$1 = 2;
+const F_ITALIC$1 = 4;
+const F_OVERLINE$1 = 8;
+const F_STRIKE$1 = 16;
+const F_INVERSE$1 = 32;
+const F_HIDDEN$1 = 64;
+const F_BLINK$1 = 128;
+const F_WIDE$1 = 256;
+const UL_SHIFT$1 = 9;
+const UL_MASK$1 = 7 << UL_SHIFT$1;
+const F_HAS_FG = 4096;
+const F_HAS_BG = 8192;
+const F_HAS_UL = 16384;
+const F_HAS_URL = 32768;
+const UL_STYLES = [
+	"none",
+	"single",
+	"double",
+	"curly",
+	"dotted",
+	"dashed"
+];
+function underlineToBits(u) {
+	const i = UL_STYLES.indexOf(u);
+	return (i < 0 ? 0 : i) << UL_SHIFT$1;
+}
+function bitsToUnderline(meta) {
+	return UL_STYLES[(meta & UL_MASK$1) >> UL_SHIFT$1] ?? "none";
+}
+/** Pack a color's 8-bit channels into a 24-bit `0xRRGGBB` word. */
+function packRgb(c) {
+	return ((c.r & 255) << 16 | (c.g & 255) << 8 | c.b & 255) >>> 0;
+}
+/** Materialize a {@link CellColor} from a packed RGB word + index (`-1` = no index). */
+function unpackColor(rgb, idx) {
+	const r = rgb >> 16 & 255;
+	const g = rgb >> 8 & 255;
+	const b = rgb & 255;
+	return idx >= 0 ? {
+		r,
+		g,
+		b,
+		index: idx
+	} : {
+		r,
+		g,
+		b
+	};
+}
+function makePackedRow(width) {
+	const meta = new Uint32Array(width);
+	const chars = new Array(width).fill("");
+	let fgRgb = null;
+	let fgIdx = null;
+	let bgRgb = null;
+	let bgIdx = null;
+	let ulRgb = null;
+	let ulIdx = null;
+	let urlMap = null;
+	function setFg(col, c) {
+		if (fgRgb === null) {
+			fgRgb = new Uint32Array(width);
+			fgIdx = new Int16Array(width);
+		}
+		fgRgb[col] = packRgb(c);
+		fgIdx[col] = c.index ?? -1;
+	}
+	function setBg(col, c) {
+		if (bgRgb === null) {
+			bgRgb = new Uint32Array(width);
+			bgIdx = new Int16Array(width);
+		}
+		bgRgb[col] = packRgb(c);
+		bgIdx[col] = c.index ?? -1;
+	}
+	function setUl(col, c) {
+		if (ulRgb === null) {
+			ulRgb = new Uint32Array(width);
+			ulIdx = new Int16Array(width);
+		}
+		ulRgb[col] = packRgb(c);
+		ulIdx[col] = c.index ?? -1;
+	}
+	function setUrl(col, u) {
+		(urlMap ??= /* @__PURE__ */ new Map()).set(col, u);
+	}
+	function clearUrl(col) {
+		if (urlMap !== null && urlMap.size > 0) urlMap.delete(col);
+	}
+	function packFlags(a, wide) {
+		let m = 0;
+		if (a.bold) m |= F_BOLD$1;
+		if (a.faint) m |= F_FAINT$1;
+		if (a.italic) m |= F_ITALIC$1;
+		if (a.overline) m |= F_OVERLINE$1;
+		if (a.strikethrough) m |= F_STRIKE$1;
+		if (a.inverse) m |= F_INVERSE$1;
+		if (a.hidden) m |= F_HIDDEN$1;
+		if (a.blink) m |= F_BLINK$1;
+		if (wide) m |= F_WIDE$1;
+		return m | underlineToBits(a.underline);
+	}
+	const row = {
+		length: width,
+		writeFromAttrs(col, ch, a, wide) {
+			let m = packFlags(a, wide);
+			chars[col] = ch;
+			if (a.fg) {
+				setFg(col, a.fg);
+				m |= F_HAS_FG;
+			}
+			if (a.bg) {
+				setBg(col, a.bg);
+				m |= F_HAS_BG;
+			}
+			if (a.underlineColor) {
+				setUl(col, a.underlineColor);
+				m |= F_HAS_UL;
+			}
+			if (a.url !== null) {
+				setUrl(col, a.url);
+				m |= F_HAS_URL;
+			} else clearUrl(col);
+			meta[col] = m;
+		},
+		setCellRaw(col, cell) {
+			let m = packFlags(cell, cell.wide);
+			chars[col] = cell.char;
+			if (cell.fg) {
+				setFg(col, cell.fg);
+				m |= F_HAS_FG;
+			}
+			if (cell.bg) {
+				setBg(col, cell.bg);
+				m |= F_HAS_BG;
+			}
+			if (cell.underlineColor) {
+				setUl(col, cell.underlineColor);
+				m |= F_HAS_UL;
+			}
+			if (cell.url !== null) {
+				setUrl(col, cell.url);
+				m |= F_HAS_URL;
+			} else clearUrl(col);
+			meta[col] = m;
+		},
+		setEmpty(col) {
+			meta[col] = 0;
+			chars[col] = "";
+			clearUrl(col);
+		},
+		eraseWithBg(col, bg) {
+			chars[col] = "";
+			clearUrl(col);
+			if (bg) {
+				setBg(col, bg);
+				meta[col] = F_HAS_BG;
+			} else meta[col] = 0;
+		},
+		widen(col) {
+			meta[col] = (meta[col] | F_WIDE$1) >>> 0;
+			if (col + 1 < width) row.setEmpty(col + 1);
+		},
+		appendChar(col, ch) {
+			chars[col] = chars[col] + ch;
+		},
+		copyCellFrom(col, src, srcCol) {
+			row.setCellRaw(col, src.getCellRaw(srcCol));
+		},
+		getCellRaw(col) {
+			const m = meta[col];
+			if (m === 0 && chars[col] === "") return emptyCell();
+			return {
+				char: chars[col],
+				fg: m & F_HAS_FG ? unpackColor(fgRgb[col], fgIdx[col]) : null,
+				bg: m & F_HAS_BG ? unpackColor(bgRgb[col], bgIdx[col]) : null,
+				bold: (m & F_BOLD$1) !== 0,
+				faint: (m & F_FAINT$1) !== 0,
+				italic: (m & F_ITALIC$1) !== 0,
+				underline: bitsToUnderline(m),
+				underlineColor: m & F_HAS_UL ? unpackColor(ulRgb[col], ulIdx[col]) : null,
+				overline: (m & F_OVERLINE$1) !== 0,
+				strikethrough: (m & F_STRIKE$1) !== 0,
+				inverse: (m & F_INVERSE$1) !== 0,
+				hidden: (m & F_HIDDEN$1) !== 0,
+				blink: (m & F_BLINK$1) !== 0,
+				wide: (m & F_WIDE$1) !== 0,
+				url: m & F_HAS_URL ? urlMap.get(col) ?? null : null
+			};
+		},
+		toCells() {
+			const out = new Array(width);
+			for (let c = 0; c < width; c++) out[c] = row.getCellRaw(c);
+			return out;
+		},
+		replaceAllFromCells(cells) {
+			for (let c = 0; c < width; c++) row.setCellRaw(c, cells[c] ?? EMPTY_CELL);
+		},
+		isEmpty(col) {
+			return meta[col] === 0 && chars[col] === "";
+		},
+		getChar(col) {
+			return chars[col];
+		},
+		isWide(col) {
+			return (meta[col] & F_WIDE$1) !== 0;
+		}
+	};
+	return row;
+}
+/** Build a packed row from a materialized cell array (reflow / restore output). */
+function packedRowFromCells(cells, width) {
+	const r = makePackedRow(width);
+	for (let c = 0; c < width; c++) r.setCellRaw(c, cells[c] ?? EMPTY_CELL);
+	return r;
+}
 const ANSI_16 = [
 	{
 		r: 0,
@@ -217,7 +459,7 @@ function isEmojiModifier(cp) {
 function createScreen(options = {}) {
 	let cols = options.cols ?? 80;
 	let rows = options.rows ?? 24;
-	const scrollbackLimit = options.scrollbackLimit ?? 1e3;
+	let scrollbackLimit = options.scrollbackLimit ?? 1e3;
 	const onResponse = options.onResponse;
 	let mainGrid = makeGrid(cols, rows);
 	let altGrid = makeGrid(cols, rows);
@@ -270,8 +512,225 @@ function createScreen(options = {}) {
 	let defaultBgColor = null;
 	let cursorColor = null;
 	const specialColors = /* @__PURE__ */ new Map();
+	let pointerFgColor = null;
+	let pointerBgColor = null;
 	let highlightBgColor = null;
 	let highlightFgColor = null;
+	const colorStack = [];
+	function cloneColor(c) {
+		return c ? { ...c } : null;
+	}
+	function snapshotColorState() {
+		return {
+			palette256: palette256.map((c) => ({ ...c })),
+			defaultFgColor: cloneColor(defaultFgColor),
+			defaultBgColor: cloneColor(defaultBgColor),
+			cursorColor: cloneColor(cursorColor),
+			specialColors: [...specialColors].map(([idx, color]) => [idx, { ...color }]),
+			pointerFgColor: cloneColor(pointerFgColor),
+			pointerBgColor: cloneColor(pointerBgColor),
+			highlightBgColor: cloneColor(highlightBgColor),
+			highlightFgColor: cloneColor(highlightFgColor)
+		};
+	}
+	function restoreColorState(snapshot) {
+		palette256 = snapshot.palette256.map((c) => ({ ...c }));
+		defaultFgColor = cloneColor(snapshot.defaultFgColor);
+		defaultBgColor = cloneColor(snapshot.defaultBgColor);
+		cursorColor = cloneColor(snapshot.cursorColor);
+		specialColors.clear();
+		for (const [idx, color] of snapshot.specialColors) specialColors.set(idx, { ...color });
+		pointerFgColor = cloneColor(snapshot.pointerFgColor);
+		pointerBgColor = cloneColor(snapshot.pointerBgColor);
+		highlightBgColor = cloneColor(snapshot.highlightBgColor);
+		highlightFgColor = cloneColor(snapshot.highlightFgColor);
+	}
+	function cloneColorStateSnapshot(snapshot) {
+		return {
+			palette256: snapshot.palette256.map((c) => ({ ...c })),
+			defaultFgColor: cloneColor(snapshot.defaultFgColor),
+			defaultBgColor: cloneColor(snapshot.defaultBgColor),
+			cursorColor: cloneColor(snapshot.cursorColor),
+			specialColors: snapshot.specialColors.map(([idx, color]) => [idx, { ...color }]),
+			pointerFgColor: cloneColor(snapshot.pointerFgColor),
+			pointerBgColor: cloneColor(snapshot.pointerBgColor),
+			highlightBgColor: cloneColor(snapshot.highlightBgColor),
+			highlightFgColor: cloneColor(snapshot.highlightFgColor)
+		};
+	}
+	function cloneAttrsSnapshot(source) {
+		return {
+			...source,
+			fg: cloneColor(source.fg),
+			bg: cloneColor(source.bg),
+			underlineColor: cloneColor(source.underlineColor)
+		};
+	}
+	function cloneCellSnapshot(source) {
+		return {
+			...source,
+			fg: cloneColor(source.fg),
+			bg: cloneColor(source.bg),
+			underlineColor: cloneColor(source.underlineColor)
+		};
+	}
+	function isDefaultEmptyCell(cell) {
+		return cell.char === "" && cell.fg === null && cell.bg === null && cell.bold === false && cell.faint === false && cell.italic === false && cell.underline === "none" && cell.underlineColor === null && cell.overline === false && cell.strikethrough === false && cell.inverse === false && cell.hidden === false && cell.blink === false && cell.wide === false && cell.url === null;
+	}
+	function restoreCellSnapshot(source) {
+		const cell = cloneCellSnapshot(source);
+		return isDefaultEmptyCell(cell) ? EMPTY_CELL : cell;
+	}
+	/** Materialize a packed grid to plain, deep-cloned Snapshot cells (index preserved). */
+	function cloneGridSnapshot(source) {
+		return source.map((row) => row.toCells().map(cloneCellSnapshot));
+	}
+	function restoreGridSnapshot(source, expectedRows, expectedCols) {
+		const out = [];
+		for (let row = 0; row < expectedRows; row++) {
+			const cells = (source[row] ?? []).slice(0, expectedCols).map(restoreCellSnapshot);
+			while (cells.length < expectedCols) cells.push(EMPTY_CELL);
+			out.push(packedRowFromCells(cells, expectedCols));
+		}
+		return out;
+	}
+	function restoreScrollbackSnapshot(source) {
+		return source.map((row) => packedRowFromCells(row.map(restoreCellSnapshot), row.length));
+	}
+	function isRecord(value) {
+		return typeof value === "object" && value !== null;
+	}
+	function assertInteger(name, value, min = 0) {
+		if (!Number.isInteger(value) || value < min) throw new TypeError(`Invalid vterm snapshot ${name}`);
+	}
+	function assertString(name, value) {
+		if (typeof value !== "string") throw new TypeError(`Invalid vterm snapshot ${name}`);
+	}
+	function assertBoolean(name, value) {
+		if (typeof value !== "boolean") throw new TypeError(`Invalid vterm snapshot ${name}`);
+	}
+	function assertRecord(name, value) {
+		if (!isRecord(value)) throw new TypeError(`Invalid vterm snapshot ${name}`);
+	}
+	function assertGrid(name, value, expectedRows, expectedCols) {
+		if (!Array.isArray(value) || value.length !== expectedRows) throw new TypeError(`Invalid vterm snapshot ${name}`);
+		for (const row of value) if (!Array.isArray(row) || row.length !== expectedCols) throw new TypeError(`Invalid vterm snapshot ${name}`);
+	}
+	function assertSoftWraps(name, value, expectedRows) {
+		if (!Array.isArray(value) || value.length !== expectedRows || value.some((entry) => typeof entry !== "boolean")) throw new TypeError(`Invalid vterm snapshot ${name}`);
+	}
+	function assertSnapshot(snapshot) {
+		const value = snapshot;
+		if (!isRecord(value)) throw new TypeError("Invalid vterm snapshot");
+		if (value.version !== 1) throw new Error(`Unsupported vterm snapshot version: ${String(value.version)}`);
+		assertInteger("cols", value.cols, 1);
+		assertInteger("rows", value.rows, 1);
+		assertInteger("scrollbackLimit", value.scrollbackLimit, 0);
+		if (value.activeBuffer !== "main" && value.activeBuffer !== "alt") throw new TypeError("Invalid vterm snapshot activeBuffer");
+		const main = value.main;
+		const alt = value.alt;
+		assertRecord("main", main);
+		assertRecord("alt", alt);
+		assertGrid("main.grid", main.grid, value.rows, value.cols);
+		assertGrid("alt.grid", alt.grid, value.rows, value.cols);
+		assertSoftWraps("main.softWrapped", main.softWrapped, value.rows);
+		assertSoftWraps("alt.softWrapped", alt.softWrapped, value.rows);
+		if (!Array.isArray(value.scrollback)) throw new TypeError("Invalid vterm snapshot scrollback");
+		if (value.scrollbackSoftWrapped !== void 0) assertSoftWraps("scrollbackSoftWrapped", value.scrollbackSoftWrapped, value.scrollback.length);
+		const cursor = value.cursor;
+		assertRecord("cursor", cursor);
+		assertInteger("cursor.x", cursor.x);
+		assertInteger("cursor.y", cursor.y);
+		assertBoolean("cursor.visible", cursor.visible);
+		if (cursor.shape !== "block" && cursor.shape !== "underline" && cursor.shape !== "bar") throw new TypeError("Invalid vterm snapshot cursor.shape");
+		assertBoolean("cursor.blinking", cursor.blinking);
+		assertInteger("cursor.savedX", cursor.savedX);
+		assertInteger("cursor.savedY", cursor.savedY);
+		const saved = value.savedState;
+		assertRecord("savedState", saved);
+		assertInteger("savedState.x", saved.x);
+		assertInteger("savedState.y", saved.y);
+		assertRecord("savedState.attrs", saved.attrs);
+		assertBoolean("savedState.originMode", saved.originMode);
+		assertBoolean("savedState.autoWrap", saved.autoWrap);
+		assertBoolean("savedState.charsetG0", saved.charsetG0);
+		assertRecord("attrs", value.attrs);
+		const modes = value.modes;
+		assertRecord("modes", modes);
+		for (const name of [
+			"bracketedPaste",
+			"applicationCursor",
+			"applicationKeypad",
+			"autoWrap",
+			"mouseTracking",
+			"sgrMouse",
+			"focusTracking",
+			"origin",
+			"insert",
+			"reverseVideo",
+			"syncOutput",
+			"kittyGraphics",
+			"colorSchemeReporting",
+			"decColumn",
+			"altScroll",
+			"utf8Mouse"
+		]) assertBoolean(`modes.${name}`, modes[name]);
+		assertInteger("modes.mouseTrackingMode", modes.mouseTrackingMode);
+		assertInteger("modes.kittyKeyboardFlags", modes.kittyKeyboardFlags);
+		if (!Array.isArray(modes.kittyKeyboardStack)) throw new TypeError("Invalid vterm snapshot modes.kittyKeyboardStack");
+		const margins = value.margins;
+		assertRecord("margins", margins);
+		assertInteger("margins.scrollTop", margins.scrollTop);
+		assertInteger("margins.scrollBottom", margins.scrollBottom);
+		assertBoolean("margins.leftRight", margins.leftRight);
+		assertInteger("margins.left", margins.left);
+		assertInteger("margins.right", margins.right);
+		const colors = value.colors;
+		assertRecord("colors", colors);
+		assertRecord("colors.current", colors.current);
+		if (!Array.isArray(colors.stack)) throw new TypeError("Invalid vterm snapshot colors.stack");
+		if (!Array.isArray(value.tabStops)) throw new TypeError("Invalid vterm snapshot tabStops");
+		for (const stop of value.tabStops) assertInteger("tabStops", stop);
+		assertString("title", value.title);
+		assertString("clipboard", value.clipboard);
+		assertString("cwd", value.cwd);
+		if (!Array.isArray(value.notifications) || value.notifications.some((entry) => typeof entry !== "string")) throw new TypeError("Invalid vterm snapshot notifications");
+		assertInteger("viewportOffset", value.viewportOffset);
+		const parser = value.parser;
+		assertRecord("parser", parser);
+		if (![
+			"ground",
+			"escape",
+			"escape_charset",
+			"escape_hash",
+			"csi",
+			"osc",
+			"dcs",
+			"dcs_passthrough",
+			"osc_st",
+			"dcs_st",
+			"apc",
+			"apc_st"
+		].includes(parser.state)) throw new TypeError("Invalid vterm snapshot parser.state");
+		assertString("parser.esc", parser.esc);
+		assertString("parser.osc", parser.osc);
+		assertString("parser.dcs", parser.dcs);
+		assertRecord("parser.dcsStart", parser.dcsStart);
+		assertInteger("parser.dcsStart.row", parser.dcsStart.row);
+		assertInteger("parser.dcsStart.col", parser.dcsStart.col);
+		assertString("parser.apc", parser.apc);
+		if (!Array.isArray(parser.utf8PendingBytes)) throw new TypeError("Invalid vterm snapshot parser.utf8PendingBytes");
+		for (const byte of parser.utf8PendingBytes) {
+			assertInteger("parser.utf8PendingBytes", byte, 0);
+			if (byte > 255) throw new TypeError("Invalid vterm snapshot parser.utf8PendingBytes");
+		}
+		const unicode = value.unicode;
+		assertRecord("unicode", unicode);
+		assertBoolean("unicode.charsetG0", unicode.charsetG0);
+		assertString("unicode.lastChar", unicode.lastChar);
+		if (unicode.pendingRegionalIndicator !== null) assertString("unicode.pendingRegionalIndicator", unicode.pendingRegionalIndicator);
+		assertBoolean("unicode.afterZWJ", unicode.afterZWJ);
+	}
 	let tabStops = defaultTabStops(cols);
 	function defaultTabStops(c) {
 		const s = /* @__PURE__ */ new Set();
@@ -288,6 +747,12 @@ function createScreen(options = {}) {
 		return 0;
 	}
 	let textScale = 1;
+	const CELL_W_PX = 8;
+	const CELL_H_PX = 17;
+	const FONT_ASCENT_PX = 14;
+	let fontSize = 12;
+	let fontWindowSize = 12;
+	let locale = "en_US.UTF-8";
 	let advancedClipboard = "";
 	let viewportOffset = 0;
 	let charsetG0 = false;
@@ -300,6 +765,7 @@ function createScreen(options = {}) {
 	let mainSoftWrapped = new Array(rows).fill(false);
 	let altSoftWrapped = new Array(rows).fill(false);
 	let softWrapped = mainSoftWrapped;
+	let scrollbackSoftWrapped = [];
 	let lastChar = "";
 	let pendingRegionalIndicator = null;
 	let afterZWJ = false;
@@ -310,16 +776,122 @@ function createScreen(options = {}) {
 	let dcsStartRow = 0;
 	let dcsStartCol = 0;
 	let apcBuf = "";
+	const opListeners = /* @__PURE__ */ new Set();
+	const parserListeners = /* @__PURE__ */ new Set();
+	let printRunParts = [];
+	let escIntermediate = "";
+	let dirtyAll = false;
+	let dirtyRows = /* @__PURE__ */ new Set();
+	let dirtyScrolled = 0;
+	let dirtyLastAbs = -1;
+	let trimmedRowCount = 0;
+	let dirtyCursor = {
+		x: 0,
+		y: 0,
+		visible: true,
+		shape: "block",
+		blinking: true
+	};
+	let sigDamageActive = false;
+	let sigDirtyAll = false;
+	let sigDirtyRows = /* @__PURE__ */ new Set();
+	let sigDirtyScrolled = 0;
+	let sigDirtyLastAbs = -1;
+	let sigDirtyCursor = {
+		x: 0,
+		y: 0,
+		visible: true,
+		shape: "block",
+		blinking: true
+	};
+	function markScreenRowDirty(screenRow) {
+		const abs = scrollback.length + screenRow;
+		if (!dirtyAll && abs !== dirtyLastAbs) {
+			dirtyLastAbs = abs;
+			dirtyRows.add(abs);
+		}
+		if (sigDamageActive && !sigDirtyAll && abs !== sigDirtyLastAbs) {
+			sigDirtyLastAbs = abs;
+			sigDirtyRows.add(abs);
+		}
+	}
+	function markAbsoluteRowDirty(abs) {
+		if (!dirtyAll && abs !== dirtyLastAbs) {
+			dirtyLastAbs = abs;
+			dirtyRows.add(abs);
+		}
+		if (sigDamageActive && !sigDirtyAll && abs !== sigDirtyLastAbs) {
+			sigDirtyLastAbs = abs;
+			sigDirtyRows.add(abs);
+		}
+	}
+	function markScreenRowsDirty(top, bottom) {
+		if (dirtyAll && (!sigDamageActive || sigDirtyAll)) return;
+		for (let r = top; r <= bottom; r++) markScreenRowDirty(r);
+	}
+	/** Structural change — the whole visible buffer is damaged. Drops the per-row set (both planes). */
+	function markAllDirty() {
+		dirtyAll = true;
+		dirtyRows.clear();
+		dirtyLastAbs = -1;
+		if (sigDamageActive) {
+			sigDirtyAll = true;
+			sigDirtyRows.clear();
+			sigDirtyLastAbs = -1;
+		}
+	}
 	const decoder = new TextDecoder();
+	const encoder = new TextEncoder();
+	let utf8PendingBytes = [];
+	function utf8SequenceLength(lead) {
+		if (lead <= 127) return 1;
+		if (lead >= 194 && lead <= 223) return 2;
+		if (lead >= 224 && lead <= 239) return 3;
+		if (lead >= 240 && lead <= 244) return 4;
+		return 0;
+	}
+	function utf8CompletePrefixLength(bytes) {
+		if (bytes.length === 0) return 0;
+		let continuationCount = 0;
+		let leadIndex = bytes.length - 1;
+		while (leadIndex >= 0 && (bytes[leadIndex] & 192) === 128 && continuationCount < 3) {
+			continuationCount++;
+			leadIndex--;
+		}
+		if (leadIndex < 0) return bytes.length;
+		const lead = bytes[leadIndex];
+		const expectedLength = utf8SequenceLength(lead);
+		if (expectedLength === 0) return bytes.length;
+		return expectedLength > bytes.length - leadIndex ? leadIndex : bytes.length;
+	}
+	function decodeInput(data) {
+		const bytes = new Uint8Array(utf8PendingBytes.length + data.length);
+		bytes.set(utf8PendingBytes, 0);
+		bytes.set(data, utf8PendingBytes.length);
+		const completeLength = utf8CompletePrefixLength(bytes);
+		utf8PendingBytes = Array.from(bytes.slice(completeLength));
+		if (completeLength === 0) return "";
+		return decoder.decode(bytes.slice(0, completeLength));
+	}
 	function makeGrid(c, r) {
 		const g = [];
 		for (let row = 0; row < r; row++) g.push(makeRow(c));
 		return g;
 	}
 	function makeRow(c) {
-		const row = [];
-		for (let col = 0; col < c; col++) row.push(EMPTY_CELL);
-		return row;
+		return makePackedRow(c);
+	}
+	/**
+	* Edit-path escape hatch for the rare column-splice operations (insert/delete
+	* chars & columns, rect fill/copy/attr): materialize the row to a fixed-length
+	* cell array, run the ordinary array edit, then repack. Length-preserving edits
+	* (splice+push/pop pairs) keep the row exactly `cols` wide. Not the hot path —
+	* plain printing goes straight through {@link PackedRow.writeFromAttrs}.
+	*/
+	function mutateRowAsCells(row, fn) {
+		const cells = row.toCells();
+		fn(cells);
+		row.replaceAllFromCells(cells);
 	}
 	function resetAttrs() {
 		return {
@@ -351,14 +923,35 @@ function createScreen(options = {}) {
 			for (let r = top; r < bottom; r++) {
 				const srcRow = grid[r + 1];
 				const dstRow = grid[r];
-				for (let c = lm; c <= rm && c < cols; c++) dstRow[c] = srcRow[c];
+				for (let c = lm; c <= rm && c < cols; c++) dstRow.copyCellFrom(c, srcRow, c);
 			}
 			const bottomRow = grid[bottom];
-			for (let c = lm; c <= rm && c < cols; c++) bottomRow[c] = EMPTY_CELL;
+			for (let c = lm; c <= rm && c < cols; c++) bottomRow.setEmpty(c);
+			markScreenRowsDirty(top, bottom);
 		} else {
-			if (grid === mainGrid && top === 0) {
+			const enteredScrollback = grid === mainGrid && top === 0;
+			if (enteredScrollback) {
 				scrollback.push(grid[0]);
-				if (scrollback.length > scrollbackLimit * 2) scrollback.splice(0, scrollback.length - scrollbackLimit);
+				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);
+					if (!dirtyAll && dirtyRows.size > 0) {
+						const shifted = /* @__PURE__ */ new Set();
+						for (const r of dirtyRows) if (r >= over) shifted.add(r - over);
+						dirtyRows = shifted;
+						dirtyLastAbs = -1;
+					}
+					if (sigDamageActive && !sigDirtyAll && sigDirtyRows.size > 0) {
+						const shifted = /* @__PURE__ */ new Set();
+						for (const r of sigDirtyRows) if (r >= over) shifted.add(r - over);
+						sigDirtyRows = shifted;
+						sigDirtyLastAbs = -1;
+					}
+					trimmedRowCount += over;
+				}
 			}
 			for (let i = top; i < bottom; i++) {
 				grid[i] = grid[i + 1];
@@ -366,6 +959,11 @@ function createScreen(options = {}) {
 			}
 			grid[bottom] = makeRow(cols);
 			softWrapped[bottom] = false;
+			if (enteredScrollback) {
+				dirtyScrolled++;
+				if (sigDamageActive) sigDirtyScrolled++;
+				markScreenRowDirty(bottom);
+			} else markScreenRowsDirty(top, bottom);
 		}
 	}
 	function scrollDown(top, bottom) {
@@ -375,10 +973,10 @@ function createScreen(options = {}) {
 			for (let r = bottom; r > top; r--) {
 				const srcRow = grid[r - 1];
 				const dstRow = grid[r];
-				for (let c = lm; c <= rm && c < cols; c++) dstRow[c] = srcRow[c];
+				for (let c = lm; c <= rm && c < cols; c++) dstRow.copyCellFrom(c, srcRow, c);
 			}
 			const topRow = grid[top];
-			for (let c = lm; c <= rm && c < cols; c++) topRow[c] = EMPTY_CELL;
+			for (let c = lm; c <= rm && c < cols; c++) topRow.setEmpty(c);
 		} else {
 			for (let i = bottom; i > top; i--) {
 				grid[i] = grid[i - 1];
@@ -387,8 +985,17 @@ function createScreen(options = {}) {
 			grid[top] = makeRow(cols);
 			softWrapped[top] = false;
 		}
+		markScreenRowsDirty(top, bottom);
 	}
-	/** Find the previous non-spacer cell (the cell before curX, skipping wide-char spacers) */
+	function scrollViewport(delta) {
+		viewportOffset = Math.max(0, Math.min(scrollback.length, viewportOffset + delta));
+	}
+	/**
+	* Locate the previous non-spacer cell position (before curX, skipping a wide-char
+	* spacer). Returns the packed row and column so callers mutate through the row's API
+	* (combining marks append, VS-16 widens). The spacer is detected structurally — a
+	* blank char whose left neighbour is wide — rather than by object identity.
+	*/
 	function getPrevCell() {
 		if (curX === 0 && curY === 0) return null;
 		let prevCol = curX - 1;
@@ -399,42 +1006,17 @@ function createScreen(options = {}) {
 			prevCol = cols - 1;
 		}
 		const row = grid[prevRow];
-		let cell = row[prevCol];
-		if (cell !== EMPTY_CELL && cell.char === "" && prevCol > 0) {
-			prevCol--;
-			cell = row[prevCol];
-		}
-		if (cell === EMPTY_CELL) return null;
+		if (prevCol > 0 && row.getChar(prevCol) === "" && row.isWide(prevCol - 1)) prevCol--;
+		if (row.isEmpty(prevCol)) return null;
 		return {
-			cell,
-			col: prevCol
+			row,
+			col: prevCol,
+			rowIdx: prevRow
 		};
 	}
-	/** Widen a cell to 2 columns, adding a spacer cell after it */
-	function widenCell(row, col, cell) {
-		cell.wide = true;
-		if (col + 1 < cols) {
-			let spacer = row[col + 1];
-			if (spacer === EMPTY_CELL) {
-				spacer = { ...EMPTY_CELL };
-				row[col + 1] = spacer;
-			}
-			spacer.char = "";
-			spacer.fg = null;
-			spacer.bg = null;
-			spacer.bold = false;
-			spacer.faint = false;
-			spacer.italic = false;
-			spacer.underline = "none";
-			spacer.underlineColor = null;
-			spacer.overline = false;
-			spacer.strikethrough = false;
-			spacer.inverse = false;
-			spacer.hidden = false;
-			spacer.blink = false;
-			spacer.wide = false;
-			spacer.url = null;
-		}
+	/** Widen the cell at `col` to 2 columns, blanking the trailing spacer at col+1. */
+	function widenCell(row, col) {
+		row.widen(col);
 	}
 	function writeChar(ch) {
 		if (charsetG0 && ch.length === 1) {
@@ -444,10 +1026,10 @@ function createScreen(options = {}) {
 		const codePoint = ch.codePointAt(0) ?? 0;
 		if (isVS16(codePoint)) {
 			const prev = getPrevCell();
-			if (prev && !prev.cell.wide) {
-				prev.cell.char += ch;
-				const row = grid[curY === 0 && curX === 0 ? 0 : curY];
-				widenCell(row, prev.col, prev.cell);
+			if (prev && !prev.row.isWide(prev.col)) {
+				prev.row.appendChar(prev.col, ch);
+				widenCell(prev.row, prev.col);
+				markScreenRowDirty(prev.rowIdx);
 				curX = prev.col + 2;
 				if (curX >= cols) curX = cols - 1;
 			}
@@ -455,18 +1037,25 @@ function createScreen(options = {}) {
 		}
 		if (isCombining(codePoint) && !isVS16(codePoint)) {
 			const prev = getPrevCell();
-			if (prev) prev.cell.char += ch;
+			if (prev) {
+				prev.row.appendChar(prev.col, ch);
+				markScreenRowDirty(prev.rowIdx);
+			}
 			return;
 		}
 		if (isEmojiModifier(codePoint)) {
 			const prev = getPrevCell();
-			if (prev) prev.cell.char += ch;
+			if (prev) {
+				prev.row.appendChar(prev.col, ch);
+				markScreenRowDirty(prev.rowIdx);
+			}
 			return;
 		}
 		if (isZWJ(codePoint)) {
 			const prev = getPrevCell();
 			if (prev) {
-				prev.cell.char += ch;
+				prev.row.appendChar(prev.col, ch);
+				markScreenRowDirty(prev.rowIdx);
 				afterZWJ = true;
 			}
 			return;
@@ -475,7 +1064,8 @@ function createScreen(options = {}) {
 			afterZWJ = false;
 			const prev = getPrevCell();
 			if (prev) {
-				prev.cell.char += ch;
+				prev.row.appendChar(prev.col, ch);
+				markScreenRowDirty(prev.rowIdx);
 				return;
 			}
 		}
@@ -511,35 +1101,18 @@ function createScreen(options = {}) {
 			}
 		} else curX = wrapBoundary - charWidth;
 		if (insertMode) {
-			const row = grid[curY];
 			const insertEnd = leftRightMarginMode ? rightMargin + 1 : cols;
-			for (let i = 0; i < charWidth; i++) {
-				row.splice(insertEnd - 1, 1);
-				row.splice(curX, 0, EMPTY_CELL);
-			}
+			mutateRowAsCells(grid[curY], (cells) => {
+				for (let i = 0; i < charWidth; i++) {
+					cells.splice(insertEnd - 1, 1);
+					cells.splice(curX, 0, emptyCell());
+				}
+			});
 		}
 		const row = grid[curY];
-		let cell = row[curX];
-		if (cell === EMPTY_CELL) {
-			cell = { ...EMPTY_CELL };
-			row[curX] = cell;
-		}
-		cell.char = ch;
-		cell.fg = attrs.fg ? { ...attrs.fg } : null;
-		cell.bg = attrs.bg ? { ...attrs.bg } : null;
-		cell.bold = attrs.bold;
-		cell.faint = attrs.faint;
-		cell.italic = attrs.italic;
-		cell.underline = attrs.underline;
-		cell.underlineColor = attrs.underlineColor ? { ...attrs.underlineColor } : null;
-		cell.overline = attrs.overline;
-		cell.strikethrough = attrs.strikethrough;
-		cell.inverse = attrs.inverse;
-		cell.hidden = attrs.hidden;
-		cell.blink = attrs.blink;
-		cell.wide = wide;
-		cell.url = attrs.url;
-		if (wide) widenCell(row, curX, cell);
+		row.writeFromAttrs(curX, ch, attrs, wide);
+		if (wide) widenCell(row, curX);
+		markScreenRowDirty(curY);
 		curX += charWidth;
 		lastChar = ch;
 	}
@@ -594,14 +1167,23 @@ function createScreen(options = {}) {
 				const charCode = parts[0] ?? 32;
 				if (charCode < 32 || charCode > 126) return;
 				const { t, l, b, r } = normalizeRect(parts[1] ?? 1, parts[2] ?? 1, parts[3] ?? rows, parts[4] ?? cols);
-				for (let row = t; row <= b && row < rows; row++) for (let col = l; col <= r && col < cols; col++) {
-					const cell = emptyCell();
-					cell.char = String.fromCharCode(charCode);
-					grid[row][col] = cell;
+				const fillChar = String.fromCharCode(charCode);
+				for (let row = t; row <= b && row < rows; row++) {
+					const gr = grid[row];
+					for (let col = l; col <= r && col < cols; col++) {
+						const cell = emptyCell();
+						cell.char = fillChar;
+						gr.setCellRaw(col, cell);
+					}
 				}
+				markScreenRowsDirty(t, Math.min(b, rows - 1));
 			} else if (finalByte === "z" || finalByte === "{") {
 				const { t, l, b, r } = normalizeRect(parts[0] ?? 1, parts[1] ?? 1, parts[2] ?? rows, parts[3] ?? cols);
-				for (let row = t; row <= b && row < rows; row++) for (let col = l; col <= r && col < cols; col++) grid[row][col] = emptyCell();
+				for (let row = t; row <= b && row < rows; row++) {
+					const gr = grid[row];
+					for (let col = l; col <= r && col < cols; col++) gr.setEmpty(col);
+				}
+				markScreenRowsDirty(t, Math.min(b, rows - 1));
 			} else if (finalByte === "v") {
 				const src = normalizeRect(parts[0] ?? 1, parts[1] ?? 1, parts[2] ?? rows, parts[3] ?? cols);
 				const dstTop = Math.max(1, parts[5] ?? 1) - 1;
@@ -610,34 +1192,35 @@ function createScreen(options = {}) {
 				const w = src.r - src.l + 1;
 				const snapshot = [];
 				for (let row = 0; row < h; row++) {
+					const srcRow = grid[src.t + row];
 					const line = [];
-					for (let col = 0; col < w; col++) {
-						const srcCell = grid[src.t + row]?.[src.l + col] ?? EMPTY_CELL;
-						line.push(srcCell === EMPTY_CELL ? EMPTY_CELL : { ...srcCell });
-					}
+					for (let col = 0; col < w; col++) line.push(srcRow ? srcRow.getCellRaw(src.l + col) : emptyCell());
 					snapshot.push(line);
 				}
 				for (let row = 0; row < h; row++) {
 					const dr = dstTop + row;
 					if (dr < 0 || dr >= rows) continue;
+					const dstRow = grid[dr];
 					for (let col = 0; col < w; col++) {
 						const dc = dstLeft + col;
 						if (dc < 0 || dc >= cols) continue;
-						grid[dr][dc] = snapshot[row][col];
+						dstRow.setCellRaw(dc, snapshot[row][col]);
 					}
 				}
+				markScreenRowsDirty(Math.max(0, dstTop), Math.min(dstTop + h - 1, rows - 1));
 			} else if (finalByte === "r" || finalByte === "t") {
 				const { t, l, b, r } = normalizeRect(parts[0] ?? 1, parts[1] ?? 1, parts[2] ?? rows, parts[3] ?? cols);
 				const sgrParts = parts.slice(4);
 				const reverse = finalByte === "t";
-				for (let row = t; row <= b && row < rows; row++) for (let col = l; col <= r && col < cols; col++) {
-					let cell = grid[row][col];
-					if (cell === EMPTY_CELL) {
-						cell = { ...EMPTY_CELL };
-						grid[row][col] = cell;
+				for (let row = t; row <= b && row < rows; row++) {
+					const gr = grid[row];
+					for (let col = l; col <= r && col < cols; col++) {
+						const cell = gr.getCellRaw(col);
+						applyRectAttrs(cell, sgrParts, reverse);
+						gr.setCellRaw(col, cell);
 					}
-					applyRectAttrs(cell, sgrParts, reverse);
 				}
+				markScreenRowsDirty(t, Math.min(b, rows - 1));
 			}
 			return;
 		}
@@ -653,11 +1236,15 @@ function createScreen(options = {}) {
 				const b = Math.min(bArg, rows) - 1;
 				const r = Math.min(rArg, cols) - 1;
 				let sum = 0;
-				for (let row = t; row <= b && row < rows; row++) for (let col = l; col <= r && col < cols; col++) {
-					const cell = grid[row]?.[col];
-					if (cell?.char) {
-						const cp = cell.char.codePointAt(0) ?? 0;
-						sum = sum + cp & 65535;
+				for (let row = t; row <= b && row < rows; row++) {
+					const gr = grid[row];
+					if (!gr) continue;
+					for (let col = l; col <= r && col < cols; col++) {
+						const ch = gr.getChar(col);
+						if (ch) {
+							const cp = ch.codePointAt(0) ?? 0;
+							sum = sum + cp & 65535;
+						}
 					}
 				}
 				const hex = sum.toString(16).toUpperCase().padStart(4, "0");
@@ -876,6 +1463,13 @@ function createScreen(options = {}) {
 			if (onResponse) {
 				if (params === "" || params === "0") onResponse("\x1BP!|00000000\x1B\\");
 			}
+		} else if (finalByte === "u") {
+			const parts = params.split(";").map((s) => s === "" ? 0 : parseInt(s, 10));
+			const flags = parts[0] ?? 0;
+			const mode = parts[1] ?? 1;
+			if (mode === 2) kittyKeyboardFlags |= flags;
+			else if (mode === 3) kittyKeyboardFlags &= ~flags;
+			else kittyKeyboardFlags = flags;
 		}
 	}
 	function handleCSIPrivate(params, intermediates, finalByte) {
@@ -997,10 +1591,12 @@ function createScreen(options = {}) {
 					useAltScreen = true;
 					grid = altGrid;
 					softWrapped = altSoftWrapped;
+					markAllDirty();
 				} else if (!set && useAltScreen) {
 					useAltScreen = false;
 					grid = mainGrid;
 					softWrapped = mainSoftWrapped;
+					markAllDirty();
 				}
 				break;
 			case 66:
@@ -1032,6 +1628,7 @@ function createScreen(options = {}) {
 					softWrapped = altSoftWrapped;
 					curX = 0;
 					curY = 0;
+					markAllDirty();
 				} else if (!set && useAltScreen) {
 					useAltScreen = false;
 					grid = mainGrid;
@@ -1039,6 +1636,7 @@ function createScreen(options = {}) {
 					curX = savedCurX;
 					curY = savedCurY;
 					clampCursor();
+					markAllDirty();
 				}
 				break;
 			case 69:
@@ -1095,6 +1693,7 @@ function createScreen(options = {}) {
 			case 3:
 				for (let row = 0; row < rows; row++) eraseCells(row, 0, row, cols - 1);
 				if (mode === 3) scrollback.length = 0;
+				markAllDirty();
 				break;
 		}
 	}
@@ -1116,11 +1715,8 @@ function createScreen(options = {}) {
 	function eraseCells(row, startCol, _endRow, endCol) {
 		const r = grid[row];
 		if (!r) return;
-		for (let col = startCol; col <= endCol && col < cols; col++) {
-			const cell = emptyCell();
-			if (attrs.bg) cell.bg = { ...attrs.bg };
-			r[col] = cell;
-		}
+		for (let col = startCol; col <= endCol && col < cols; col++) r.eraseWithBg(col, attrs.bg);
+		markScreenRowDirty(row);
 	}
 	function handleInsertLines(count) {
 		if (curY < scrollTop || curY > scrollBottom) return;
@@ -1133,32 +1729,36 @@ function createScreen(options = {}) {
 	function handleDeleteChars(count) {
 		const row = grid[curY];
 		if (!row) return;
-		if (leftRightMarginMode && (leftMargin > 0 || rightMargin < cols - 1)) {
-			for (let i = 0; i < count; i++) if (curX <= rightMargin) {
-				row.splice(curX, 1);
-				row.splice(rightMargin, 0, emptyCell());
+		mutateRowAsCells(row, (cells) => {
+			if (leftRightMarginMode && (leftMargin > 0 || rightMargin < cols - 1)) {
+				for (let i = 0; i < count; i++) if (curX <= rightMargin) {
+					cells.splice(curX, 1);
+					cells.splice(rightMargin, 0, emptyCell());
+				}
+			} else for (let i = 0; i < count; i++) if (curX < cols) {
+				cells.splice(curX, 1);
+				cells.push(emptyCell());
 			}
-		} else for (let i = 0; i < count; i++) if (curX < cols) {
-			row.splice(curX, 1);
-			row.push(emptyCell());
-		}
+		});
+		markScreenRowDirty(curY);
 	}
 	function handleInsertChars(count) {
 		const row = grid[curY];
 		if (!row) return;
-		if (leftRightMarginMode && (leftMargin > 0 || rightMargin < cols - 1)) for (let i = 0; i < count; i++) {
-			row.splice(rightMargin, 1);
-			row.splice(curX, 0, emptyCell());
-		}
-		else for (let i = 0; i < count; i++) {
-			row.splice(curX, 0, emptyCell());
-			row.pop();
-		}
+		mutateRowAsCells(row, (cells) => {
+			if (leftRightMarginMode && (leftMargin > 0 || rightMargin < cols - 1)) for (let i = 0; i < count; i++) {
+				cells.splice(rightMargin, 1);
+				cells.splice(curX, 0, emptyCell());
+			}
+			else for (let i = 0; i < count; i++) {
+				cells.splice(curX, 0, emptyCell());
+				cells.pop();
+			}
+		});
+		markScreenRowDirty(curY);
 	}
 	function handleEraseChars(count) {
-		const row = grid[curY];
-		if (!row) return;
-		for (let i = 0; i < count && curX + i < cols; i++) row[curX + i] = emptyCell();
+		eraseCells(curY, curX, curY, Math.min(curX + count - 1, cols - 1));
 	}
 	/** Bounds of the active scroll/margin rectangle (inclusive). */
 	function activeRect() {
@@ -1176,9 +1776,11 @@ function createScreen(options = {}) {
 			if (!r) continue;
 			for (let col = left; col <= right; col++) {
 				const src = col + count;
-				r[col] = src <= right ? r[src] : emptyCell();
+				if (src <= right) r.copyCellFrom(col, r, src);
+				else r.setEmpty(col);
 			}
 		}
+		markScreenRowsDirty(top, bottom);
 	}
 	function handleShiftRight(count) {
 		const { top, left, bottom, right } = activeRect();
@@ -1187,9 +1789,11 @@ function createScreen(options = {}) {
 			if (!r) continue;
 			for (let col = right; col >= left; col--) {
 				const src = col - count;
-				r[col] = src >= left ? r[src] : emptyCell();
+				if (src >= left) r.copyCellFrom(col, r, src);
+				else r.setEmpty(col);
 			}
 		}
+		markScreenRowsDirty(top, bottom);
 	}
 	function handleInsertColumn(count) {
 		const { top, left, bottom, right } = activeRect();
@@ -1197,9 +1801,10 @@ function createScreen(options = {}) {
 		for (let row = top; row <= bottom; row++) {
 			const r = grid[row];
 			if (!r) continue;
-			for (let col = right; col >= curX + count; col--) r[col] = r[col - count];
-			for (let col = curX; col < curX + count && col <= right; col++) r[col] = emptyCell();
+			for (let col = right; col >= curX + count; col--) r.copyCellFrom(col, r, col - count);
+			for (let col = curX; col < curX + count && col <= right; col++) r.setEmpty(col);
 		}
+		markScreenRowsDirty(top, bottom);
 	}
 	function handleDeleteColumn(count) {
 		const { top, left, bottom, right } = activeRect();
@@ -1207,9 +1812,10 @@ function createScreen(options = {}) {
 		for (let row = top; row <= bottom; row++) {
 			const r = grid[row];
 			if (!r) continue;
-			for (let col = curX; col + count <= right; col++) r[col] = r[col + count];
-			for (let col = right - count + 1; col <= right && col >= 0; col++) r[col] = emptyCell();
+			for (let col = curX; col + count <= right; col++) r.copyCellFrom(col, r, col + count);
+			for (let col = right - count + 1; col <= right && col >= 0; col++) r.setEmpty(col);
 		}
+		markScreenRowsDirty(top, bottom);
 	}
 	/**
 	* Apply (or reverse-toggle) a list of SGR attribute codes to a single cell.
@@ -1363,7 +1969,10 @@ function createScreen(options = {}) {
 				case 35:
 				case 36:
 				case 37:
-					attrs.fg = { ...palette256[code - 30] };
+					attrs.fg = {
+						...palette256[code - 30],
+						index: code - 30
+					};
 					break;
 				case 38: {
 					const subs = subParams.get(i);
@@ -1390,7 +1999,10 @@ function createScreen(options = {}) {
 				case 45:
 				case 46:
 				case 47:
-					attrs.bg = { ...palette256[code - 40] };
+					attrs.bg = {
+						...palette256[code - 40],
+						index: code - 40
+					};
 					break;
 				case 48: {
 					const subs = subParams.get(i);
@@ -1440,7 +2052,10 @@ function createScreen(options = {}) {
 				case 95:
 				case 96:
 				case 97:
-					attrs.fg = { ...palette256[code - 90 + 8] };
+					attrs.fg = {
+						...palette256[code - 90 + 8],
+						index: code - 90 + 8
+					};
 					break;
 				case 100:
 				case 101:
@@ -1450,7 +2065,10 @@ function createScreen(options = {}) {
 				case 105:
 				case 106:
 				case 107:
-					attrs.bg = { ...palette256[code - 100 + 8] };
+					attrs.bg = {
+						...palette256[code - 100 + 8],
+						index: code - 100 + 8
+					};
 					break;
 			}
 			i++;
@@ -1461,12 +2079,16 @@ function createScreen(options = {}) {
 		const type = params[startIndex + 1];
 		if (type === 5 && startIndex + 2 < params.length) {
 			const idx = params[startIndex + 2];
+			const entry = palette256[idx];
 			return {
-				color: { ...palette256[idx] ?? {
+				color: entry ? {
+					...entry,
+					index: idx
+				} : {
 					r: 0,
 					g: 0,
 					b: 0
-				} },
+				},
 				nextIndex: startIndex + 3
 			};
 		} else if (type === 2 && startIndex + 4 < params.length) return {
@@ -1485,11 +2107,15 @@ function createScreen(options = {}) {
 		const type = subs[1];
 		if (type === 5 && subs.length >= 3) {
 			const idx = subs[2];
-			return { ...palette256[idx] ?? {
+			const entry = palette256[idx];
+			return entry ? {
+				...entry,
+				index: idx
+			} : {
 				r: 0,
 				g: 0,
 				b: 0
-			} };
+			};
 		} else if (type === 2) {
 			if (subs.length >= 5) {
 				if (subs.length >= 6) return {
@@ -1582,7 +2208,10 @@ function createScreen(options = {}) {
 					if (isNaN(idx) || idx < 0 || idx > 4) continue;
 					if (spec === "?") {
 						const c = specialColors.get(idx);
-						if (onResponse) onResponse(`\x1b]5;${idx};${c ? formatColorResponse(c) : "rgb:0000/0000/0000"}\x1b\\`);
+						if (onResponse) {
+							const payload = c ? formatColorResponse(c) : "rgb:0000/0000/0000";
+							onResponse(`\x1b]5;${idx};${payload}\x1b\\`);
+						}
 					} else {
 						const c = parseColorSpec(spec);
 						if (c) specialColors.set(idx, c);
@@ -1626,6 +2255,30 @@ function createScreen(options = {}) {
 					if (c) cursorColor = c;
 				}
 				break;
+			case 13:
+				if (value === "?") {
+					if (onResponse) onResponse(`\x1b]13;${formatColorResponse(pointerFgColor ?? defaultFgColor ?? {
+						r: 255,
+						g: 255,
+						b: 255
+					})}\x1b\\`);
+				} else {
+					const c = parseColorSpec(value);
+					if (c) pointerFgColor = c;
+				}
+				break;
+			case 14:
+				if (value === "?") {
+					if (onResponse) onResponse(`\x1b]14;${formatColorResponse(pointerBgColor ?? defaultBgColor ?? {
+						r: 0,
+						g: 0,
+						b: 0
+					})}\x1b\\`);
+				} else {
+					const c = parseColorSpec(value);
+					if (c) pointerBgColor = c;
+				}
+				break;
 			case 17:
 				if (value === "?") {
 					if (onResponse) onResponse(`\x1b]17;${formatColorResponse(highlightBgColor ?? defaultFgColor ?? {
@@ -1755,6 +2408,12 @@ function createScreen(options = {}) {
 			case 112:
 				cursorColor = null;
 				break;
+			case 113:
+				pointerFgColor = null;
+				break;
+			case 114:
+				pointerBgColor = null;
+				break;
 			case 117:
 				highlightBgColor = null;
 				break;
@@ -1766,7 +2425,10 @@ function createScreen(options = {}) {
 				if (clipSemi !== -1) {
 					const data = value.substring(clipSemi + 1);
 					if (data === "?") {
-						if (onResponse) onResponse(`\x1b]52;c;${btoa(clipboard)}\x1b\\`);
+						if (onResponse) {
+							const encoded = btoa(clipboard);
+							onResponse(`\x1b]52;c;${encoded}\x1b\\`);
+						}
 					} else {
 						try {
 							clipboard = atob(data);
@@ -1820,9 +2482,58 @@ function createScreen(options = {}) {
 					}
 				}
 				break;
+			case 701:
+				if (value === "?") {
+					if (onResponse) onResponse(`\x1b]701;${locale}\x1b\\`);
+				} else if (value !== "") locale = value;
+				break;
+			case 702:
+				if (onResponse) onResponse("\x1B]702;vterm.js;vterm;0;2\x1B\\");
+				break;
+			case 720: {
+				const n = parseInt(value, 10);
+				scrollViewport(!isNaN(n) && n > 0 ? n : 1);
+				break;
+			}
+			case 721: {
+				const n = parseInt(value, 10);
+				scrollViewport(-(!isNaN(n) && n > 0 ? n : 1));
+				break;
+			}
+			case 776:
+				if (onResponse) onResponse(`\x1b]776;${CELL_W_PX};${CELL_H_PX};${FONT_ASCENT_PX}\x1b\\`);
+				break;
+			case 7770:
+				if (value === "?") {
+					if (onResponse) onResponse(`\x1b]7770;${fontSize}\x1b\\`);
+				} else if (value === "") fontSize = 12;
+				else {
+					const n = parseInt(value, 10);
+					if (!isNaN(n) && n > 0) fontSize = n;
+				}
+				break;
+			case 7777:
+				if (value === "?") {
+					if (onResponse) onResponse(`\x1b]7777;${fontWindowSize}\x1b\\`);
+				} else if (value === "") fontWindowSize = 12;
+				else {
+					const n = parseInt(value, 10);
+					if (!isNaN(n) && n > 0) fontWindowSize = n;
+				}
+				break;
+			case 30001:
+				colorStack.push(snapshotColorState());
+				break;
+			case 30101: {
+				const snapshot = colorStack.pop();
+				if (snapshot) restoreColorState(snapshot);
+				break;
+			}
 			case 5522:
-				if (value === "?" && onResponse) onResponse(`\x1b]5522;${btoa(advancedClipboard)}\x1b\\`);
-				else try {
+				if (value === "?" && onResponse) {
+					const encoded = btoa(advancedClipboard);
+					onResponse(`\x1b]5522;${encoded}\x1b\\`);
+				} else try {
 					advancedClipboard = atob(value);
 				} catch {
 					advancedClipboard = "";
@@ -1851,8 +2562,10 @@ function createScreen(options = {}) {
 			return;
 		}
 		if (data.startsWith("+q") && onResponse) {
-			if (data.substring(2) === "544e") onResponse(`\x1bP1+r544e=${Array.from(new TextEncoder().encode("vterm")).map((b) => b.toString(16).padStart(2, "0")).join("")}\x1b\\`);
-			else onResponse("\x1BP0+r\x1B\\");
+			if (data.substring(2) === "544e") {
+				const hexValue = Array.from(new TextEncoder().encode("vterm")).map((b) => b.toString(16).padStart(2, "0")).join("");
+				onResponse(`\x1bP1+r544e=${hexValue}\x1b\\`);
+			} else onResponse("\x1BP0+r\x1B\\");
 			return;
 		}
 	}
@@ -1898,6 +2611,7 @@ function createScreen(options = {}) {
 		altGrid = makeGrid(cols, rows);
 		grid = mainGrid;
 		scrollback = [];
+		scrollbackSoftWrapped = [];
 		curX = 0;
 		curY = 0;
 		curVisible = true;
@@ -1943,6 +2657,9 @@ function createScreen(options = {}) {
 		altScrollMode = false;
 		utf8MouseMode = false;
 		textScale = 1;
+		fontSize = 12;
+		fontWindowSize = 12;
+		locale = "en_US.UTF-8";
 		advancedClipboard = "";
 		viewportOffset = 0;
 		charsetG0 = false;
@@ -1954,8 +2671,11 @@ function createScreen(options = {}) {
 		defaultBgColor = null;
 		cursorColor = null;
 		specialColors.clear();
+		pointerFgColor = null;
+		pointerBgColor = null;
 		highlightBgColor = null;
 		highlightFgColor = null;
+		colorStack.length = 0;
 		tabStops = defaultTabStops(cols);
 		lastChar = "";
 		pendingRegionalIndicator = null;
@@ -1963,14 +2683,87 @@ function createScreen(options = {}) {
 		parserState = "ground";
 		escBuf = "";
 		oscBuf = "";
+		dcsBuf = "";
+		dcsStartRow = 0;
+		dcsStartCol = 0;
 		apcBuf = "";
+		utf8PendingBytes = [];
 		semanticZones = [];
 		mainSoftWrapped = new Array(rows).fill(false);
 		altSoftWrapped = new Array(rows).fill(false);
 		softWrapped = mainSoftWrapped;
+		markAllDirty();
+		dirtyScrolled = 0;
+		if (sigDamageActive) sigDirtyScrolled = 0;
+		trimmedRowCount = 0;
+		flushSignals();
+	}
+	function emitParserEvent(ev) {
+		for (const listener of parserListeners) listener(ev);
+	}
+	function flushPrintRun() {
+		if (printRunParts.length === 0) return;
+		const text = printRunParts.join("");
+		printRunParts = [];
+		emitParserEvent({
+			kind: "print",
+			text
+		});
+	}
+	function emitExecute(code) {
+		if (parserListeners.size === 0) return;
+		flushPrintRun();
+		emitParserEvent({
+			kind: "execute",
+			code
+		});
+	}
+	function emitCsiEvent(rawParams, intermediates, final) {
+		if (parserListeners.size === 0) return;
+		flushPrintRun();
+		let prefix;
+		let body = rawParams;
+		const marker = body.charCodeAt(0);
+		if (marker === 63 || marker === 62 || marker === 60 || marker === 61) {
+			prefix = body[0];
+			body = body.slice(1);
+		}
+		const ev = {
+			kind: "csi",
+			final,
+			params: body.split(";").map((s) => s === "" ? 0 : parseInt(s, 10))
+		};
+		if (prefix !== void 0) ev.prefix = prefix;
+		if (intermediates !== "") ev.intermediates = intermediates;
+		emitParserEvent(ev);
+	}
+	function emitOscEvent(osc) {
+		if (parserListeners.size === 0) return;
+		const semi = osc.indexOf(";");
+		const code = semi === -1 ? parseInt(osc, 10) : parseInt(osc.slice(0, semi), 10);
+		if (Number.isNaN(code)) return;
+		flushPrintRun();
+		emitParserEvent({
+			kind: "osc",
+			code,
+			data: semi === -1 ? "" : osc.slice(semi + 1)
+		});
+	}
+	function emitEsc(final, intermediates) {
+		if (parserListeners.size === 0) return;
+		flushPrintRun();
+		const ev = {
+			kind: "esc",
+			final
+		};
+		if (intermediates !== "") ev.intermediates = intermediates;
+		emitParserEvent(ev);
+	}
+	function emitOp(op) {
+		for (const listener of opListeners) listener(op);
 	}
 	function process(data) {
-		const text = decoder.decode(data, { stream: true });
+		const text = decodeInput(data);
 		for (let i = 0; i < text.length; i++) {
 			const ch = text[i];
 			const code = text.charCodeAt(i);
@@ -1979,18 +2772,25 @@ function createScreen(options = {}) {
 					if (code === 27) {
 						parserState = "escape";
 						escBuf = "";
-					} else if (code === 7) {} else if (code === 8) {
+					} else if (code === 7) emitExecute(7);
+					else if (code === 8) {
 						if (curX > 0) curX--;
-					} else if (code === 9) curX = nextTabStop(curX);
-					else if (code === 10 || code === 11 || code === 12) {
+						emitExecute(8);
+					} else if (code === 9) {
+						curX = nextTabStop(curX);
+						emitExecute(9);
+					} else if (code === 10 || code === 11 || code === 12) {
 						softWrapped[curY] = false;
 						curY++;
 						if (curY > scrollBottom) {
 							curY = scrollBottom;
 							scrollUp(scrollTop, scrollBottom);
 						}
-					} else if (code === 13) curX = 0;
-					else if (code >= 32) {
+						emitExecute(code);
+					} else if (code === 13) {
+						curX = 0;
+						emitExecute(13);
+					} else if (code >= 32) {
 						let char = ch;
 						if (code >= 55296 && code <= 56319 && i + 1 < text.length) {
 							const nextCode = text.charCodeAt(i + 1);
@@ -2000,6 +2800,7 @@ function createScreen(options = {}) {
 							}
 						}
 						writeChar(char);
+						if (parserListeners.size > 0) printRunParts.push(char);
 					}
 					break;
 				case "escape":
@@ -2018,6 +2819,7 @@ function createScreen(options = {}) {
 					} else if (ch === "c") {
 						fullReset();
 						parserState = "ground";
+						emitEsc("c", "");
 					} else if (ch === "D") {
 						curY++;
 						if (curY > scrollBottom) {
@@ -2025,6 +2827,7 @@ function createScreen(options = {}) {
 							scrollUp(scrollTop, scrollBottom);
 						}
 						parserState = "ground";
+						emitEsc("D", "");
 					} else if (ch === "M") {
 						curY--;
 						if (curY < scrollTop) {
@@ -2032,6 +2835,7 @@ function createScreen(options = {}) {
 							scrollDown(scrollTop, scrollBottom);
 						}
 						parserState = "ground";
+						emitEsc("M", "");
 					} else if (ch === "7") {
 						savedState = {
 							curX,
@@ -2047,6 +2851,7 @@ function createScreen(options = {}) {
 							charsetG0
 						};
 						parserState = "ground";
+						emitEsc("7", "");
 					} else if (ch === "8") {
 						curX = savedState.curX;
 						curY = savedState.curY;
@@ -2061,6 +2866,7 @@ function createScreen(options = {}) {
 						charsetG0 = savedState.charsetG0;
 						clampCursor();
 						parserState = "ground";
+						emitEsc("8", "");
 					} else if (ch === "E") {
 						curX = 0;
 						curY++;
@@ -2069,18 +2875,28 @@ function createScreen(options = {}) {
 							scrollUp(scrollTop, scrollBottom);
 						}
 						parserState = "ground";
+						emitEsc("E", "");
 					} else if (ch === "H") {
 						tabStops.add(curX);
 						parserState = "ground";
-					} else if (ch === "#") parserState = "escape_hash";
-					else if (ch === "(") parserState = "escape_charset";
-					else if (ch === ")") parserState = "escape_charset";
-					else if (ch === "=") {
+						emitEsc("H", "");
+					} else if (ch === "#") {
+						escIntermediate = "#";
+						parserState = "escape_hash";
+					} else if (ch === "(") {
+						escIntermediate = "(";
+						parserState = "escape_charset";
+					} else if (ch === ")") {
+						escIntermediate = ")";
+						parserState = "escape_charset";
+					} else if (ch === "=") {
 						applicationKeypad = true;
 						parserState = "ground";
+						emitEsc("=", "");
 					} else if (ch === ">") {
 						applicationKeypad = false;
 						parserState = "ground";
+						emitEsc(">", "");
 					} else if (ch === "_") {
 						parserState = "apc";
 						apcBuf = "";
@@ -2090,22 +2906,22 @@ function createScreen(options = {}) {
 					if (ch === "0") charsetG0 = true;
 					else charsetG0 = false;
 					parserState = "ground";
+					emitEsc(ch, escIntermediate);
 					break;
 				case "escape_hash":
 					if (ch === "8") {
+						const alignCell = emptyCell();
+						alignCell.char = "E";
 						for (let r = 0; r < rows; r++) {
 							const row = grid[r];
-							for (let c = 0; c < cols; c++) {
-								const cell = emptyCell();
-								cell.char = "E";
-								row[c] = cell;
-							}
+							for (let c = 0; c < cols; c++) row.setCellRaw(c, alignCell);
 							softWrapped[r] = false;
 						}
 						curX = 0;
 						curY = 0;
 					}
 					parserState = "ground";
+					emitEsc(ch, escIntermediate);
 					break;
 				case "csi":
 					if (code >= 64 && code <= 126) {
@@ -2127,6 +2943,7 @@ function createScreen(options = {}) {
 						else if (paramPart.startsWith("=")) handleCSIEq(paramPart.substring(1), intermediatePart, ch);
 						else handleCSI(paramPart, intermediatePart, ch);
 						parserState = "ground";
+						emitCsiEvent(paramPart, intermediatePart, ch);
 					} else if (escBuf.length >= 256) parserState = "ground";
 					else escBuf += ch;
 					break;
@@ -2134,14 +2951,18 @@ function createScreen(options = {}) {
 					if (code === 7) {
 						handleOSC(oscBuf);
 						parserState = "ground";
+						emitOscEvent(oscBuf);
 					} else if (code === 27) parserState = "osc_st";
 					else if (oscBuf.length >= 4096) parserState = "ground";
 					else oscBuf += ch;
 					break;
-				case "osc_st":
-					if (ch === "\\") handleOSC(oscBuf);
+				case "osc_st": {
+					const oscComplete = ch === "\\";
+					if (oscComplete) handleOSC(oscBuf);
 					parserState = "ground";
+					if (oscComplete) emitOscEvent(oscBuf);
 					break;
+				}
 				case "dcs":
 					if (code === 27) parserState = "dcs_st";
 					else if (code === 7) {
@@ -2169,6 +2990,12 @@ function createScreen(options = {}) {
 					break;
 			}
 		}
+		flushPrintRun();
+		if (opListeners.size > 0) emitOp({
+			type: "output",
+			data
+		});
+		flushSignals();
 	}
 	/**
 	* Reconstruct logical lines from a grid, joining rows that were soft-wrapped.
@@ -2180,7 +3007,7 @@ function createScreen(options = {}) {
 		for (let r = 0; r < srcRows; r++) {
 			const row = srcGrid[r];
 			if (!row) continue;
-			for (let c = 0; c < row.length; c++) currentLine.push(row[c]);
+			for (let c = 0; c < row.length; c++) currentLine.push(row.getCellRaw(c));
 			if (srcSoftWrapped[r]) continue;
 			logical.push(currentLine);
 			currentLine = [];
@@ -2190,20 +3017,34 @@ function createScreen(options = {}) {
 	}
 	/**
 	* Re-wrap logical lines to a new column width, producing grid rows and soft-wrap flags.
+	*
+	* `track` names one position — a logical line index plus a cell offset
+	* within that line (the cursor, expressed content-relative) — and the
+	* returned `tracked` reports the output row/col it lands on, so `resize()`
+	* can move the cursor WITH its logical line instead of leaving it at its
+	* old absolute row. An offset at/beyond the trimmed line end (cursor in
+	* trailing blanks or one past the last cell) lands after the last emitted
+	* cell, advanced by the leftover distance, clamped to the row.
 	*/
-	function rewrapLines(logicalLines, newCols) {
+	function rewrapLines(logicalLines, newCols, track) {
 		const outRows = [];
 		const outWrapped = [];
-		for (const line of logicalLines) {
+		let tracked = null;
+		for (let li = 0; li < logicalLines.length; li++) {
+			const line = logicalLines[li];
 			let lineLen = line.length;
 			while (lineLen > 0) {
 				const cell = line[lineLen - 1];
-				if (cell === EMPTY_CELL || cell.char === "" && !cell.wide) lineLen--;
+				if (cell.char === "" && !cell.wide) lineLen--;
 				else break;
 			}
 			if (lineLen === 0) {
 				outRows.push(makeRow(newCols));
 				outWrapped.push(false);
+				if (track !== void 0 && track.line === li) tracked = {
+					row: outRows.length - 1,
+					col: Math.min(track.offset, newCols - 1)
+				};
 				continue;
 			}
 			let pos = 0;
@@ -2213,34 +3054,65 @@ function createScreen(options = {}) {
 				while (col < newCols && pos < lineLen) {
 					const cell = line[pos];
 					if (cell.wide && col + 2 > newCols) break;
-					row[col] = cell === EMPTY_CELL ? EMPTY_CELL : { ...cell };
+					if (track !== void 0 && track.line === li && pos === track.offset) tracked = {
+						row: outRows.length,
+						col
+					};
+					row.setCellRaw(col, cell);
 					col++;
 					pos++;
 				}
 				const moreContent = pos < lineLen;
 				outRows.push(row);
 				outWrapped.push(moreContent);
+				if (!moreContent && track !== void 0 && track.line === li && tracked === null) {
+					const extra = track.offset - lineLen;
+					tracked = {
+						row: outRows.length - 1,
+						col: Math.min(newCols - 1, col + extra)
+					};
+				}
 			}
 		}
 		return {
 			rows: outRows,
-			wrapped: outWrapped
+			wrapped: outWrapped,
+			tracked
 		};
 	}
+	/** True when a packed row has no printable content (all columns blank). */
+	function packedRowIsBlank(row) {
+		for (let c = 0; c < row.length; c++) if (!(row.getChar(c) === "" && !row.isWide(c))) return false;
+		return true;
+	}
 	/**
 	* Trim trailing empty rows from reflowed result, so they don't push content off the top
 	* when we take the last newRows rows.
 	*/
 	function trimTrailingEmptyRows(result) {
-		while (result.rows.length > 1) if (result.rows[result.rows.length - 1].every((cell) => cell === EMPTY_CELL || cell.char === "" && !cell.wide) && !result.wrapped[result.rows.length - 2]) {
-			result.rows.pop();
-			result.wrapped.pop();
-		} else break;
+		while (result.rows.length > 1) {
+			const lastRow = result.rows[result.rows.length - 1];
+			if (packedRowIsBlank(lastRow) && !result.wrapped[result.rows.length - 2]) {
+				result.rows.pop();
+				result.wrapped.pop();
+			} else break;
+		}
 	}
 	function resize(newCols, newRows) {
-		const mainResult = rewrapLines(getLogicalLines(mainGrid, mainSoftWrapped, rows), newCols);
+		if (newCols === cols && newRows === rows) return;
+		const activeWrappedPre = useAltScreen ? altSoftWrapped : mainSoftWrapped;
+		const cursorRowPre = Math.min(Math.max(curY, 0), rows - 1);
+		let cursorLineStart = cursorRowPre;
+		while (cursorLineStart > 0 && activeWrappedPre[cursorLineStart - 1]) cursorLineStart--;
+		let cursorLineIdx = 0;
+		for (let r = 0; r < cursorLineStart; r++) if (!activeWrappedPre[r]) cursorLineIdx++;
+		const cursorTrack = {
+			line: cursorLineIdx,
+			offset: (cursorRowPre - cursorLineStart) * cols + curX
+		};
+		const mainResult = rewrapLines(getLogicalLines(mainGrid, mainSoftWrapped, rows), newCols, useAltScreen ? void 0 : cursorTrack);
 		trimTrailingEmptyRows(mainResult);
-		const altResult = rewrapLines(getLogicalLines(altGrid, altSoftWrapped, rows), newCols);
+		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);
@@ -2256,6 +3128,12 @@ function createScreen(options = {}) {
 			newAlt[r] = altResult.rows[altStartRow + r];
 			newAltWrapped[r] = altResult.wrapped[altStartRow + r];
 		}
+		const activeResult = useAltScreen ? altResult : mainResult;
+		const activeStartRow = useAltScreen ? altStartRow : mainStartRow;
+		if (activeResult.tracked !== null) {
+			curY = Math.min(activeResult.tracked.row, activeResult.rows.length) - activeStartRow;
+			curX = activeResult.tracked.col;
+		}
 		mainGrid = newMain;
 		altGrid = newAlt;
 		mainSoftWrapped = newMainWrapped;
@@ -2271,31 +3149,265 @@ function createScreen(options = {}) {
 		rightMargin = cols - 1;
 		if (newCols > oldCols) for (let i = Math.max(8, Math.ceil(oldCols / 8) * 8); i < newCols; i += 8) tabStops.add(i);
 		clampCursor();
+		markAllDirty();
+		if (opListeners.size > 0) emitOp({
+			type: "resize",
+			cols: newCols,
+			rows: newRows
+		});
+		flushSignals();
+	}
+	function snapshot() {
+		return {
+			version: 1,
+			cols,
+			rows,
+			scrollbackLimit,
+			activeBuffer: useAltScreen ? "alt" : "main",
+			main: {
+				grid: cloneGridSnapshot(mainGrid),
+				softWrapped: [...mainSoftWrapped]
+			},
+			alt: {
+				grid: cloneGridSnapshot(altGrid),
+				softWrapped: [...altSoftWrapped]
+			},
+			scrollback: cloneGridSnapshot(scrollback),
+			scrollbackSoftWrapped: [...scrollbackSoftWrapped],
+			cursor: {
+				x: curX,
+				y: curY,
+				visible: curVisible,
+				shape: cursorShape,
+				blinking: cursorBlinking,
+				savedX: savedCurX,
+				savedY: savedCurY
+			},
+			savedState: {
+				x: savedState.curX,
+				y: savedState.curY,
+				attrs: cloneAttrsSnapshot(savedState.attrs),
+				originMode: savedState.originMode,
+				autoWrap: savedState.autoWrap,
+				charsetG0: savedState.charsetG0
+			},
+			attrs: cloneAttrsSnapshot(attrs),
+			modes: {
+				bracketedPaste,
+				applicationCursor,
+				applicationKeypad,
+				autoWrap,
+				mouseTracking,
+				mouseTrackingMode,
+				sgrMouse,
+				focusTracking,
+				origin: originMode,
+				insert: insertMode,
+				reverseVideo,
+				syncOutput,
+				kittyKeyboardFlags,
+				kittyKeyboardStack: [...kittyKeyboardStack],
+				kittyGraphics: hasKittyGraphics,
+				colorSchemeReporting,
+				decColumn: decColumnMode,
+				altScroll: altScrollMode,
+				utf8Mouse: utf8MouseMode
+			},
+			margins: {
+				scrollTop,
+				scrollBottom,
+				leftRight: leftRightMarginMode,
+				left: leftMargin,
+				right: rightMargin
+			},
+			colors: {
+				current: snapshotColorState(),
+				stack: colorStack.map(cloneColorStateSnapshot)
+			},
+			tabStops: [...tabStops].sort((a, b) => a - b),
+			title,
+			clipboard,
+			cwd,
+			notifications: [...notifications],
+			viewportOffset,
+			parser: {
+				state: parserState,
+				esc: escBuf,
+				osc: oscBuf,
+				dcs: dcsBuf,
+				dcsStart: {
+					row: dcsStartRow,
+					col: dcsStartCol
+				},
+				apc: apcBuf,
+				utf8PendingBytes: [...utf8PendingBytes]
+			},
+			unicode: {
+				charsetG0,
+				lastChar,
+				pendingRegionalIndicator,
+				afterZWJ
+			}
+		};
+	}
+	function restore(snapshotValue) {
+		assertSnapshot(snapshotValue);
+		cols = snapshotValue.cols;
+		rows = snapshotValue.rows;
+		scrollbackLimit = snapshotValue.scrollbackLimit;
+		mainGrid = restoreGridSnapshot(snapshotValue.main.grid, rows, cols);
+		altGrid = restoreGridSnapshot(snapshotValue.alt.grid, rows, cols);
+		scrollback = restoreScrollbackSnapshot(snapshotValue.scrollback);
+		scrollbackSoftWrapped = snapshotValue.scrollbackSoftWrapped ? [...snapshotValue.scrollbackSoftWrapped] : new Array(scrollback.length).fill(false);
+		mainSoftWrapped = [...snapshotValue.main.softWrapped];
+		altSoftWrapped = [...snapshotValue.alt.softWrapped];
+		useAltScreen = snapshotValue.activeBuffer === "alt";
+		grid = useAltScreen ? altGrid : mainGrid;
+		softWrapped = useAltScreen ? altSoftWrapped : mainSoftWrapped;
+		curX = snapshotValue.cursor.x;
+		curY = snapshotValue.cursor.y;
+		curVisible = snapshotValue.cursor.visible;
+		cursorShape = snapshotValue.cursor.shape;
+		cursorBlinking = snapshotValue.cursor.blinking;
+		savedCurX = snapshotValue.cursor.savedX;
+		savedCurY = snapshotValue.cursor.savedY;
+		savedState = {
+			curX: snapshotValue.savedState.x,
+			curY: snapshotValue.savedState.y,
+			attrs: cloneAttrsSnapshot(snapshotValue.savedState.attrs),
+			originMode: snapshotValue.savedState.originMode,
+			autoWrap: snapshotValue.savedState.autoWrap,
+			charsetG0: snapshotValue.savedState.charsetG0
+		};
+		attrs = cloneAttrsSnapshot(snapshotValue.attrs);
+		bracketedPaste = snapshotValue.modes.bracketedPaste;
+		applicationCursor = snapshotValue.modes.applicationCursor;
+		applicationKeypad = snapshotValue.modes.applicationKeypad;
+		autoWrap = snapshotValue.modes.autoWrap;
+		mouseTracking = snapshotValue.modes.mouseTracking;
+		mouseTrackingMode = snapshotValue.modes.mouseTrackingMode;
+		sgrMouse = snapshotValue.modes.sgrMouse;
+		focusTracking = snapshotValue.modes.focusTracking;
+		originMode = snapshotValue.modes.origin;
+		insertMode = snapshotValue.modes.insert;
+		reverseVideo = snapshotValue.modes.reverseVideo;
+		syncOutput = snapshotValue.modes.syncOutput;
+		kittyKeyboardFlags = snapshotValue.modes.kittyKeyboardFlags;
+		kittyKeyboardStack = [...snapshotValue.modes.kittyKeyboardStack];
+		hasKittyGraphics = snapshotValue.modes.kittyGraphics;
+		colorSchemeReporting = snapshotValue.modes.colorSchemeReporting;
+		decColumnMode = snapshotValue.modes.decColumn;
+		altScrollMode = snapshotValue.modes.altScroll;
+		utf8MouseMode = snapshotValue.modes.utf8Mouse;
+		scrollTop = snapshotValue.margins.scrollTop;
+		scrollBottom = snapshotValue.margins.scrollBottom;
+		leftRightMarginMode = snapshotValue.margins.leftRight;
+		leftMargin = snapshotValue.margins.left;
+		rightMargin = snapshotValue.margins.right;
+		restoreColorState(snapshotValue.colors.current);
+		colorStack.length = 0;
+		colorStack.push(...snapshotValue.colors.stack.map(cloneColorStateSnapshot));
+		tabStops = new Set(snapshotValue.tabStops);
+		title = snapshotValue.title;
+		clipboard = snapshotValue.clipboard;
+		cwd = snapshotValue.cwd;
+		notifications = [...snapshotValue.notifications];
+		viewportOffset = Math.max(0, Math.min(scrollback.length, snapshotValue.viewportOffset));
+		parserState = snapshotValue.parser.state;
+		escBuf = snapshotValue.parser.esc;
+		oscBuf = snapshotValue.parser.osc;
+		dcsBuf = snapshotValue.parser.dcs;
+		dcsStartRow = snapshotValue.parser.dcsStart.row;
+		dcsStartCol = snapshotValue.parser.dcsStart.col;
+		apcBuf = snapshotValue.parser.apc;
+		utf8PendingBytes = [...snapshotValue.parser.utf8PendingBytes];
+		charsetG0 = snapshotValue.unicode.charsetG0;
+		lastChar = snapshotValue.unicode.lastChar;
+		pendingRegionalIndicator = snapshotValue.unicode.pendingRegionalIndicator;
+		afterZWJ = snapshotValue.unicode.afterZWJ;
+		textScale = 1;
+		fontSize = 12;
+		fontWindowSize = 12;
+		locale = "en_US.UTF-8";
+		advancedClipboard = "";
+		semanticZones = [];
+		hasSixel = false;
+		sixelImages = [];
+		if (curX < 0) curX = 0;
+		if (curX > cols) curX = cols;
+		if (curY < 0) curY = 0;
+		if (curY >= rows) curY = rows - 1;
+		markAllDirty();
+		dirtyScrolled = 0;
+		if (sigDamageActive) sigDirtyScrolled = 0;
+		trimmedRowCount = 0;
+		flushSignals();
 	}
 	function getCell(row, col) {
 		const r = grid[row];
 		if (!r || col >= cols) return emptyCell();
-		return { ...r[col] };
+		return stripCellColorIndex(r.getCellRaw(col));
 	}
 	function getLine(row) {
 		const r = grid[row];
-		if (!r) return makeRow(cols);
-		return r.map((cell) => ({ ...cell }));
+		if (!r) return makeRow(cols).toCells();
+		return r.toCells().map(stripCellColorIndex);
 	}
 	function getText() {
 		const lines = [];
 		for (let r = 0; r < rows; r++) lines.push(rowToString(grid[r]));
 		return lines.join("\n");
 	}
+	function getScrollbackText() {
+		const lines = [];
+		for (const row of scrollback) lines.push(rowToString(row));
+		return lines.join("\n");
+	}
+	function totalRows() {
+		return scrollback.length + rows;
+	}
+	function screenRows() {
+		return rows;
+	}
+	function viewportTop() {
+		return scrollback.length - viewportOffset;
+	}
+	function getRowAbsolute(row) {
+		if (row < 0 || row >= scrollback.length + rows) return makeRow(cols).toCells();
+		return (row < scrollback.length ? scrollback[row] : grid[row - scrollback.length]).toCells().map(stripCellColorIndex);
+	}
+	function firstRetainedRow() {
+		return trimmedRowCount;
+	}
+	function takeDirty() {
+		const cursorChanged = curX !== dirtyCursor.x || curY !== dirtyCursor.y || curVisible !== dirtyCursor.visible || cursorShape !== dirtyCursor.shape || cursorBlinking !== dirtyCursor.blinking;
+		const region = {
+			rows: dirtyAll ? "all" : dirtyRows,
+			cursor: cursorChanged,
+			scrolled: dirtyScrolled
+		};
+		dirtyRows = /* @__PURE__ */ new Set();
+		dirtyAll = false;
+		dirtyScrolled = 0;
+		dirtyLastAbs = -1;
+		dirtyCursor = {
+			x: curX,
+			y: curY,
+			visible: curVisible,
+			shape: cursorShape,
+			blinking: cursorBlinking
+		};
+		return region;
+	}
 	function rowToString(row) {
 		let line = "";
 		for (let i = 0; i < row.length; i++) {
-			const cell = row[i];
-			if (cell.wide) line += cell.char;
-			else if (cell.char === "") {
-				if (i > 0 && row[i - 1]?.wide) continue;
+			const ch = row.getChar(i);
+			if (row.isWide(i)) line += ch;
+			else if (ch === "") {
+				if (i > 0 && row.isWide(i - 1)) continue;
 				line += " ";
-			} else line += cell.char;
+			} else line += ch;
 		}
 		return line.replace(/\s+$/, "");
 	}
@@ -2308,10 +3420,10 @@ function createScreen(options = {}) {
 			const colEnd = row === endRow ? endCol : cols;
 			let line = "";
 			for (let col = colStart; col < colEnd; col++) {
-				const cell = r[col];
-				if (!cell) continue;
-				if (cell.char === "" && col > 0 && r[col - 1]?.wide) continue;
-				line += cell.char || " ";
+				if (col < 0 || col >= r.length) continue;
+				const ch = r.getChar(col);
+				if (ch === "" && col > 0 && r.isWide(col - 1)) continue;
+				line += ch || " ";
 			}
 			parts.push(line.replace(/\s+$/, ""));
 		}
@@ -2341,6 +3453,176 @@ function createScreen(options = {}) {
 			default: return false;
 		}
 	}
+	function apply(op) {
+		switch (op.type) {
+			case "output":
+				process(typeof op.data === "string" ? encoder.encode(op.data) : op.data);
+				return;
+			case "resize":
+				resize(op.cols, op.rows);
+				return;
+			default: throw new Error(`vterm.apply: unhandled op ${JSON.stringify(op)}`);
+		}
+	}
+	function tapOps(listener) {
+		opListeners.add(listener);
+		return () => {
+			opListeners.delete(listener);
+		};
+	}
+	function tapParser(listener) {
+		parserListeners.add(listener);
+		return () => {
+			parserListeners.delete(listener);
+		};
+	}
+	const stateFlushSignals = [];
+	/**
+	* A state signal (title/modes/cursor/size): `get()` reads live; `subscribe` captures the current
+	* value as its baseline (so only later changes deliver) and `flush()` delivers once per flush
+	* boundary iff the value changed. Registered in `stateFlushSignals` so `flushSignals` visits it.
+	*/
+	function makeStateSignal(read, eq) {
+		const listeners = /* @__PURE__ */ new Set();
+		let last = read();
+		const signal = {
+			get: read,
+			subscribe(listener) {
+				if (listeners.size === 0) last = read();
+				listeners.add(listener);
+				return () => {
+					listeners.delete(listener);
+				};
+			},
+			flush() {
+				if (listeners.size === 0) return;
+				const current = read();
+				if (eq(current, last)) return;
+				last = current;
+				for (const listener of listeners) listener(current);
+			}
+		};
+		stateFlushSignals.push(signal);
+		return signal;
+	}
+	function modesNow() {
+		return {
+			altScreen: useAltScreen,
+			cursorVisible: curVisible,
+			bracketedPaste,
+			applicationCursor,
+			applicationKeypad,
+			autoWrap,
+			mouseTracking,
+			mouseTrackingMode,
+			sgrMouse,
+			utf8Mouse: utf8MouseMode,
+			focusTracking,
+			originMode,
+			insertMode,
+			reverseVideo,
+			syncOutput,
+			leftRightMargin: leftRightMarginMode,
+			colorSchemeReporting,
+			kittyKeyboard: kittyKeyboardFlags > 0,
+			kittyGraphics: hasKittyGraphics,
+			sixel: hasSixel
+		};
+	}
+	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;
+	}
+	const damageListeners = /* @__PURE__ */ new Set();
+	let damageLast = {
+		rows: /* @__PURE__ */ new Set(),
+		cursor: false,
+		scrolled: 0
+	};
+	let damageSignal;
+	function getDamageSignal() {
+		return damageSignal ??= {
+			get: () => damageLast,
+			subscribe(listener) {
+				if (damageListeners.size === 0) {
+					sigDamageActive = true;
+					sigDirtyAll = false;
+					sigDirtyRows = /* @__PURE__ */ new Set();
+					sigDirtyScrolled = 0;
+					sigDirtyLastAbs = -1;
+					sigDirtyCursor = {
+						x: curX,
+						y: curY,
+						visible: curVisible,
+						shape: cursorShape,
+						blinking: cursorBlinking
+					};
+				}
+				damageListeners.add(listener);
+				return () => {
+					damageListeners.delete(listener);
+					if (damageListeners.size === 0) sigDamageActive = false;
+				};
+			}
+		};
+	}
+	function emitDamageBatch() {
+		const cursorChanged = curX !== sigDirtyCursor.x || curY !== sigDirtyCursor.y || curVisible !== sigDirtyCursor.visible || cursorShape !== sigDirtyCursor.shape || cursorBlinking !== sigDirtyCursor.blinking;
+		if (!sigDirtyAll && sigDirtyRows.size === 0 && sigDirtyScrolled === 0 && !cursorChanged) return;
+		const region = {
+			rows: sigDirtyAll ? "all" : sigDirtyRows,
+			cursor: cursorChanged,
+			scrolled: sigDirtyScrolled
+		};
+		sigDirtyRows = /* @__PURE__ */ new Set();
+		sigDirtyAll = false;
+		sigDirtyScrolled = 0;
+		sigDirtyLastAbs = -1;
+		sigDirtyCursor = {
+			x: curX,
+			y: curY,
+			visible: curVisible,
+			shape: cursorShape,
+			blinking: cursorBlinking
+		};
+		damageLast = region;
+		for (const listener of damageListeners) listener(region);
+	}
+	let signalsFacade;
+	let titleSignal;
+	let modesSignal;
+	let cursorSignal;
+	let sizeSignal;
+	function getSignals() {
+		return signalsFacade ??= {
+			get title$() {
+				return titleSignal ??= makeStateSignal(() => title, (a, b) => a === b);
+			},
+			get modes$() {
+				return modesSignal ??= makeStateSignal(modesNow, modesEq);
+			},
+			get cursor$() {
+				return cursorSignal ??= makeStateSignal(() => ({
+					col: curX,
+					row: curY
+				}), (a, b) => a.col === b.col && a.row === b.row);
+			},
+			get size$() {
+				return sizeSignal ??= makeStateSignal(() => ({
+					cols,
+					rows
+				}), (a, b) => a.cols === b.cols && a.rows === b.rows);
+			},
+			get damage$() {
+				return getDamageSignal();
+			}
+		};
+	}
+	/** Coalesced end-of-call emission for every accessed signal — the flush boundary (§4). */
+	function flushSignals() {
+		if (signalsFacade === void 0) return;
+		for (const signal of stateFlushSignals) signal.flush();
+		if (sigDamageActive) emitDamageBatch();
+	}
 	return {
 		get cols() {
 			return cols;
@@ -2348,13 +3630,33 @@ function createScreen(options = {}) {
 		get rows() {
 			return rows;
 		},
+		get signals() {
+			return getSignals();
+		},
 		process,
 		resize,
+		apply,
+		tapOps,
+		tapParser,
 		reset: fullReset,
+		snapshot,
+		restore,
 		getCell,
+		getRow: getLine,
 		getLine,
 		getText,
+		getScrollbackText,
 		getTextRange,
+		totalRows,
+		screenRows,
+		viewportTop,
+		getRowAbsolute,
+		firstRetainedRow,
+		takeDirty,
+		getCursor: () => ({
+			col: curX,
+			row: curY
+		}),
 		getCursorPosition: () => ({
 			x: curX,
 			y: curY
@@ -2369,12 +3671,890 @@ function createScreen(options = {}) {
 		getNotifications: () => [...notifications],
 		getScrollbackLength: () => scrollback.length,
 		getViewportOffset: () => viewportOffset,
-		scrollViewport: (delta) => {
-			viewportOffset = Math.max(0, Math.min(scrollback.length, viewportOffset + delta));
-		},
+		scrollViewport,
 		getSemanticZones: () => semanticZones.map((z) => ({ ...z })),
-		getSixelImages: () => sixelImages.map((img) => ({ ...img }))
+		getSixelImages: () => sixelImages.map((img) => ({ ...img })),
+		serialize: (options) => serializeSnapshot(snapshot(), options)
+	};
+}
+const SERIALIZE_DEFAULT_PEN = Object.freeze({
+	fg: null,
+	bg: null,
+	bold: false,
+	faint: false,
+	italic: false,
+	underline: "none",
+	underlineColor: null,
+	overline: false,
+	strikethrough: false,
+	inverse: false,
+	hidden: false,
+	blink: false
+});
+const SERIALIZE_BOOL_CODES = [
+	["bold", "1"],
+	["faint", "2"],
+	["italic", "3"],
+	["blink", "5"],
+	["inverse", "7"],
+	["hidden", "8"],
+	["strikethrough", "9"],
+	["overline", "53"]
+];
+/** Colon-subparam underline forms — the lossless spellings vterm itself parses. */
+function serializeUnderlineParam(style) {
+	switch (style) {
+		case "single": return "4";
+		case "double": return "4:2";
+		case "curly": return "4:3";
+		case "dotted": return "4:4";
+		case "dashed": return "4:5";
+		case "none": return "24";
+	}
+}
+function serializeColorEq(a, b) {
+	if (a === null || b === null) return a === b;
+	return a.r === b.r && a.g === b.g && a.b === b.b && a.index === b.index;
+}
+function serializePenOf(source) {
+	return {
+		fg: source.fg,
+		bg: source.bg,
+		bold: source.bold,
+		faint: source.faint,
+		italic: source.italic,
+		underline: source.underline,
+		underlineColor: source.underlineColor,
+		overline: source.overline,
+		strikethrough: source.strikethrough,
+		inverse: source.inverse,
+		hidden: source.hidden,
+		blink: source.blink
+	};
+}
+function serializePenEq(a, b) {
+	return a.bold === b.bold && a.faint === b.faint && a.italic === b.italic && a.blink === b.blink && a.inverse === b.inverse && a.hidden === b.hidden && a.strikethrough === b.strikethrough && a.overline === b.overline && a.underline === b.underline && serializeColorEq(a.fg, b.fg) && serializeColorEq(a.bg, b.bg) && serializeColorEq(a.underlineColor, b.underlineColor);
+}
+function serializePenIsDefault(pen) {
+	return serializePenEq(pen, SERIALIZE_DEFAULT_PEN);
+}
+function serializeColorParams(prefix, defaultCode, color) {
+	if (color === null) return defaultCode;
+	const idx = color.index;
+	if (idx !== void 0 && idx >= 0 && idx <= 255) {
+		if (prefix === "38") {
+			if (idx <= 7) return String(30 + idx);
+			if (idx <= 15) return String(90 + (idx - 8));
+			return `38;5;${String(idx)}`;
+		}
+		if (prefix === "48") {
+			if (idx <= 7) return String(40 + idx);
+			if (idx <= 15) return String(100 + (idx - 8));
+			return `48;5;${String(idx)}`;
+		}
+		return `${prefix};5;${String(idx)}`;
+	}
+	return `${prefix};2;${String(color.r)};${String(color.g)};${String(color.b)}`;
+}
+/**
+* Reset-on-removal pen diff (the tmux `grid_string_cells` model): emit `SGR 0`
+* iff a boolean attribute turns off or the underline changes away from a
+* non-none style, then re-add deltas from the reset base. This makes the
+* `SGR 22` bold/faint coupling and the underline-off classes structurally
+* impossible, at a few bytes' cost. The leading `0` is emitted only on an
+* actual reset (not whenever the previous pen happens to be default) so
+* output stays byte-deterministic and idempotence-friendly.
+*/
+function serializeDiffPen(prev, cur) {
+	let boolOff = false;
+	for (const [key] of SERIALIZE_BOOL_CODES) if (prev[key] === true && cur[key] === false) {
+		boolOff = true;
+		break;
+	}
+	const underlineChanged = prev.underline !== cur.underline && prev.underline !== "none";
+	const reset = boolOff || underlineChanged;
+	const base = reset ? SERIALIZE_DEFAULT_PEN : prev;
+	const out = reset ? ["0"] : [];
+	for (const [key, code] of SERIALIZE_BOOL_CODES) if (cur[key] === true && base[key] === false) out.push(code);
+	if (cur.underline !== base.underline) out.push(serializeUnderlineParam(cur.underline));
+	if (!serializeColorEq(cur.fg, base.fg)) out.push(serializeColorParams("38", "39", cur.fg));
+	if (!serializeColorEq(cur.bg, base.bg)) out.push(serializeColorParams("48", "49", cur.bg));
+	if (!serializeColorEq(cur.underlineColor, base.underlineColor)) out.push(serializeColorParams("58", "59", cur.underlineColor));
+	return out;
+}
+/**
+* Last cell worth emitting: trailing UNWRITTEN cells (`char === ""`, default
+* pen, no url) are trimmed — the receiver's cleared screen already has them.
+* Erased-with-bg trailing cells (BCE) are kept and reproduced via ECH.
+*/
+function serializeRowEnd(row) {
+	let end = row.length;
+	while (end > 0) {
+		const cell = row[end - 1];
+		if (cell === void 0) {
+			end--;
+			continue;
+		}
+		if (cell.char.length > 0 || cell.wide || cell.url !== null) break;
+		if (!serializePenIsDefault(serializePenOf(cell))) break;
+		end--;
+	}
+	return end;
+}
+/**
+* Encode one row with per-run pen diffing. Invariants:
+* - the terminal pen is DEFAULT at entry (rows end with `SGR 0`);
+* - wide-cell spacers (char `""` following a `wide` cell) emit nothing;
+* - runs of unwritten cells are SKIPPED via CHA (the sink's cells stay
+*   genuinely empty — not painted as spaces), and erased-with-bg runs are
+*   reproduced via SGR+ECH, so the sink grid equals the source grid natively;
+* - an open OSC 8 hyperlink is always closed by row end.
+*
+* `literalWidth > 0` switches to LITERAL mode for soft-wrap-linked history
+* rows: every one of `literalWidth` columns is WRITTEN (unwritten cells as
+* pen-carrying spaces — no CHA skips, no ECH, no trailing trim), so the last
+* column write arms the receiver's pending-wrap and the next row's first
+* character re-links the logical line. Cell-level cost: the receiver's
+* scrollback holds written spaces where the source had unwritten cells —
+* invisible to the text + wrap-bit projections that scrollback serves.
+*/
+function serializeEncodeRow(row, hyperlinks, literalWidth = 0) {
+	const literal = literalWidth > 0;
+	const end = literal ? literalWidth : serializeRowEnd(row);
+	let out = "";
+	let pen = SERIALIZE_DEFAULT_PEN;
+	let openUrl = null;
+	let col = 0;
+	while (col < end) {
+		const cell = row[col];
+		if (cell === void 0) {
+			if (!literal) {
+				col++;
+				continue;
+			}
+			const diff = serializeDiffPen(pen, SERIALIZE_DEFAULT_PEN);
+			if (diff.length > 0) {
+				out += `\x1b[${diff.join(";")}m`;
+				pen = SERIALIZE_DEFAULT_PEN;
+				if (diff[0] === "0") openUrl = null;
+			}
+			if (openUrl !== null) {
+				out += "\x1B]8;;\x1B\\";
+				openUrl = null;
+			}
+			out += " ";
+			col++;
+			continue;
+		}
+		if (cell.char.length === 0 && col > 0 && row[col - 1]?.wide === true) {
+			col++;
+			continue;
+		}
+		if (cell.char.length === 0 && cell.url === null && !literal) {
+			const runPen = serializePenOf(cell);
+			const runStart = col;
+			while (col < end) {
+				const next = row[col];
+				if (next === void 0 || next.char.length > 0 || next.url !== null) break;
+				if (!serializePenEq(serializePenOf(next), runPen)) break;
+				col++;
+			}
+			const runLength = col - runStart;
+			if (serializePenIsDefault(runPen)) out += `\x1b[${String(col + 1)}G`;
+			else {
+				const diff = serializeDiffPen(pen, runPen);
+				if (diff.length > 0) {
+					out += `\x1b[${diff.join(";")}m`;
+					pen = runPen;
+					if (diff[0] === "0") openUrl = null;
+				}
+				out += `\x1b[${String(runLength)}X\x1b[${String(col + 1)}G`;
+			}
+			continue;
+		}
+		const cellPen = serializePenOf(cell);
+		const diff = serializeDiffPen(pen, cellPen);
+		if (diff.length > 0) {
+			out += `\x1b[${diff.join(";")}m`;
+			pen = cellPen;
+			if (diff[0] === "0") openUrl = null;
+		}
+		const url = hyperlinks ? cell.url : null;
+		if (url !== openUrl) {
+			out += url === null ? "\x1B]8;;\x1B\\" : `\x1b]8;;${url}\x1b\\`;
+			openUrl = url;
+		}
+		out += cell.char.length > 0 ? cell.char : " ";
+		col++;
+	}
+	if (openUrl !== null) out += "\x1B]8;;\x1B\\";
+	return out;
+}
+/**
+* Paint-safe DECSET boolean flags emitted in phase 3 — set-forms only, emitted
+* only when true (the receiver is fresh: every flag defaults to false). Origin
+* and insert are deliberately NOT here — they corrupt a positioned paint and
+* are restored in finalize instead.
+*/
+const SERIALIZE_DECSET_FLAGS = [
+	["applicationCursor", 1],
+	["reverseVideo", 5],
+	["focusTracking", 1004],
+	["utf8Mouse", 1005],
+	["sgrMouse", 1006],
+	["altScroll", 1007],
+	["bracketedPaste", 2004],
+	["colorSchemeReporting", 2031]
+];
+/** Default palette shared by every serialize call (read-only baseline for OSC 4 diffs). */
+const SERIALIZE_DEFAULT_PALETTE = buildPalette256();
+/** `rgb:RR/GG/BB` — the XParseColor spelling vterm's own OSC parser round-trips exactly. */
+function serializeColorSpec(color) {
+	const hex = (v) => v.toString(16).padStart(2, "0");
+	return `rgb:${hex(color.r)}/${hex(color.g)}/${hex(color.b)}`;
+}
+/** DECSCUSR code for (shape, blinking); 1 (blinking block) is the fresh default. */
+function serializeCursorStyleCode(shape, blinking) {
+	const base = shape === "block" ? 1 : shape === "underline" ? 3 : 5;
+	return blinking ? base : base + 1;
+}
+/** True when `stops` (sorted) is exactly the fresh default — a stop every 8 columns. */
+function serializeTabStopsAreDefault(stops, cols) {
+	let expected = 8;
+	for (const stop of stops) {
+		if (stop !== expected) return false;
+		expected += 8;
+	}
+	return expected >= cols;
+}
+/**
+* Serialize a snapshot to minimal ANSI a FRESH same-size terminal can replay.
+* Phase order + the hard exclusion set are documented on the section header
+* above; every ordering constraint is pinned by the mode round-trip matrix.
+*
+* Intended divergences (documented, not silent): syncOutput/decColumn are
+* never emitted; the inactive buffer, SCP saved cursor, DECSC saved state,
+* color stack, and parser/pending-wrap/mid-parse state are unserializable to
+* a VT byte stream by design — the binary snapshot carries them.
+*/
+function serializeSnapshot(snapshot, options = {}) {
+	const hyperlinks = options.hyperlinks !== false;
+	const excluded = new Set(options.excludeModes ?? []);
+	const rows = snapshot.rows;
+	const m = snapshot.modes;
+	const out = [];
+	if (options.includeScrollback !== false && snapshot.scrollback.length > 0) {
+		const wraps = snapshot.scrollbackSoftWrapped;
+		const last = snapshot.scrollback.length - 1;
+		for (let i = 0; i < snapshot.scrollback.length; i++) {
+			const row = snapshot.scrollback[i];
+			if (wraps?.[i] === true && i < last) out.push(serializeEncodeRow(row, hyperlinks, snapshot.cols), "\x1B[0m");
+			else out.push(serializeEncodeRow(row, hyperlinks), "\x1B[0m\r\n");
+		}
+		if (rows > 1) out.push("\n".repeat(rows - 1));
+	}
+	if (snapshot.activeBuffer === "alt") out.push("\x1B[?1049h");
+	if (snapshot.margins.scrollTop !== 0 || snapshot.margins.scrollBottom !== rows - 1) out.push(`\x1b[${String(snapshot.margins.scrollTop + 1)};${String(snapshot.margins.scrollBottom + 1)}r`);
+	for (const [key, code] of SERIALIZE_DECSET_FLAGS) if (m[key] === true && !excluded.has(key)) out.push(`\x1b[?${String(code)}h`);
+	if (m.mouseTracking && m.mouseTrackingMode > 0 && !excluded.has("mouseTracking")) out.push(`\x1b[?${String(m.mouseTrackingMode)}h`);
+	if (m.applicationKeypad && !excluded.has("applicationKeypad")) out.push("\x1B=");
+	if (!excluded.has("kittyKeyboardFlags") && (m.kittyKeyboardFlags !== 0 || m.kittyKeyboardStack.length > 0)) {
+		const stack = m.kittyKeyboardStack;
+		if (stack.length === 0) out.push(`\x1b[=${String(m.kittyKeyboardFlags)}u`);
+		else {
+			out.push(`\x1b[=${String(stack[0])}u`);
+			for (let i = 1; i < stack.length; i++) out.push(`\x1b[>${String(stack[i])}u`);
+			out.push(`\x1b[>${String(m.kittyKeyboardFlags)}u`);
+		}
+	}
+	const colors = snapshot.colors.current;
+	if (colors.defaultFgColor) out.push(`\x1b]10;${serializeColorSpec(colors.defaultFgColor)}\x1b\\`);
+	if (colors.defaultBgColor) out.push(`\x1b]11;${serializeColorSpec(colors.defaultBgColor)}\x1b\\`);
+	for (let i = 0; i < colors.palette256.length; i++) {
+		const cur = colors.palette256[i];
+		const def = SERIALIZE_DEFAULT_PALETTE[i];
+		if (cur !== void 0 && def !== void 0 && !serializeColorEq(cur, def)) out.push(`\x1b]4;${String(i)};${serializeColorSpec(cur)}\x1b\\`);
+	}
+	if (options.includeTitle === true && snapshot.title.length > 0) out.push(`\x1b]0;${snapshot.title}\x1b\\`);
+	out.push("\x1B[?7l", "\x1B[H\x1B[2J");
+	const grid = snapshot.activeBuffer === "alt" ? snapshot.alt.grid : snapshot.main.grid;
+	for (let r = 0; r < rows; r++) {
+		const line = serializeEncodeRow(grid[r] ?? [], hyperlinks);
+		if (line.length === 0) continue;
+		out.push(`\x1b[${String(r + 1)};1H`, line, "\x1B[0m");
+	}
+	out.push(m.autoWrap ? "\x1B[?7h" : "\x1B[?7l");
+	if (snapshot.cursor.shape !== "block" || !snapshot.cursor.blinking) out.push(`\x1b[${String(serializeCursorStyleCode(snapshot.cursor.shape, snapshot.cursor.blinking))} q`);
+	if (snapshot.unicode.charsetG0) out.push("\x1B(0");
+	if (m.insert && !excluded.has("insert")) out.push("\x1B[4h");
+	if (!serializeTabStopsAreDefault(snapshot.tabStops, snapshot.cols)) {
+		out.push("\x1B[3g");
+		for (const stop of snapshot.tabStops) if (stop < snapshot.cols) out.push(`\x1b[${String(stop + 1)}G\x1bH`);
+	}
+	if (snapshot.margins.leftRight) {
+		out.push("\x1B[?69h");
+		if (snapshot.margins.left !== 0 || snapshot.margins.right !== snapshot.cols - 1) out.push(`\x1b[${String(snapshot.margins.left + 1)};${String(snapshot.margins.right + 1)}s`);
+	}
+	const penParams = serializeDiffPen(SERIALIZE_DEFAULT_PEN, serializePenOf(snapshot.attrs));
+	if (penParams.length > 0) out.push(`\x1b[${penParams.join(";")}m`);
+	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;
+	if (origin && inRegion) {
+		out.push("\x1B[?6h");
+		out.push(`\x1b[${String(snapshot.cursor.y - snapshot.margins.scrollTop + 1)};${String(snapshot.cursor.x + 1)}H`);
+	} else {
+		out.push(`\x1b[${String(snapshot.cursor.y + 1)};${String(snapshot.cursor.x + 1)}H`);
+		if (origin) out.push("\x1B[?6h");
+	}
+	return out.join("");
+}
+//#endregion
+//#region src/snapshot-codec.ts
+const VERSION = 1;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const F_BOLD = 1;
+const F_FAINT = 2;
+const F_ITALIC = 4;
+const F_OVERLINE = 8;
+const F_STRIKE = 16;
+const F_INVERSE = 32;
+const F_HIDDEN = 64;
+const F_BLINK = 128;
+const F_WIDE = 256;
+const UL_SHIFT = 9;
+const UL_MASK = 7;
+const UNDERLINE_STYLES = [
+	"none",
+	"single",
+	"double",
+	"curly",
+	"dotted",
+	"dashed"
+];
+const UNDERLINE_INDEX = {
+	none: 0,
+	single: 1,
+	double: 2,
+	curly: 3,
+	dotted: 4,
+	dashed: 5
+};
+function createWriter() {
+	let buf = /* @__PURE__ */ new Uint8Array(1024);
+	let len = 0;
+	function ensure(extra) {
+		if (len + extra <= buf.length) return;
+		let cap = buf.length;
+		while (cap < len + extra) cap *= 2;
+		const next = new Uint8Array(cap);
+		next.set(buf.subarray(0, len));
+		buf = next;
+	}
+	return {
+		u8(byte) {
+			ensure(1);
+			buf[len++] = byte & 255;
+		},
+		varint(value) {
+			ensure(10);
+			let v = value;
+			while (v >= 128) {
+				buf[len++] = v % 128 + 128;
+				v = Math.floor(v / 128);
+			}
+			buf[len++] = v;
+		},
+		bytes(src) {
+			ensure(src.length);
+			buf.set(src, len);
+			len += src.length;
+		},
+		finish() {
+			return buf.slice(0, len);
+		}
+	};
+}
+function createReader(bytes) {
+	let pos = 0;
+	function u8() {
+		if (pos >= bytes.length) throw new Error("vterm snapshot codec: unexpected end of input");
+		return bytes[pos++];
+	}
+	return {
+		u8,
+		varint() {
+			let result = 0;
+			let shift = 1;
+			for (;;) {
+				const byte = u8();
+				result += (byte & 127) * shift;
+				if ((byte & 128) === 0) break;
+				shift *= 128;
+				if (shift > 2 ** 53) throw new Error("vterm snapshot codec: varint too large");
+			}
+			return result;
+		},
+		take(n) {
+			if (pos + n > bytes.length) throw new Error("vterm snapshot codec: unexpected end of input");
+			const slice = bytes.subarray(pos, pos + n);
+			pos += n;
+			return slice;
+		}
+	};
+}
+function createRunAccumulator() {
+	const runs = [];
+	let hasLast = false;
+	let lastValue = 0;
+	return {
+		runs,
+		push(value) {
+			if (hasLast && value === lastValue) runs[runs.length - 2] += 1;
+			else {
+				runs.push(1, value);
+				lastValue = value;
+				hasLast = true;
+			}
+		}
+	};
+}
+function writeRuns(w, runs) {
+	w.varint(runs.length / 2);
+	for (let i = 0; i < runs.length; i += 2) {
+		w.varint(runs[i]);
+		w.varint(runs[i + 1]);
+	}
+}
+function readRuns(r) {
+	const runCount = r.varint();
+	const runs = [];
+	for (let i = 0; i < runCount; i++) {
+		const count = r.varint();
+		const value = r.varint();
+		runs.push(count, value);
+	}
+	return runs;
+}
+function createRunCursor(runs) {
+	let total = 0;
+	for (let i = 0; i < runs.length; i += 2) total += runs[i];
+	let idx = 0;
+	let remaining = runs.length > 0 ? runs[0] : 0;
+	let value = runs.length > 1 ? runs[1] : 0;
+	return {
+		total,
+		next() {
+			while (remaining === 0) {
+				idx += 2;
+				if (idx >= runs.length) throw new Error("vterm snapshot codec: run-length underflow");
+				remaining = runs[idx];
+				value = runs[idx + 1];
+			}
+			remaining -= 1;
+			return value;
+		}
+	};
+}
+function expandLengths(runs) {
+	const out = [];
+	for (let i = 0; i < runs.length; i += 2) {
+		const count = runs[i];
+		const value = runs[i + 1];
+		for (let k = 0; k < count; k++) out.push(value);
+	}
+	return out;
+}
+function writeBits(w, bits) {
+	let acc = 0;
+	let n = 0;
+	for (const bit of bits) {
+		if (bit) acc |= 1 << n;
+		n++;
+		if (n === 8) {
+			w.u8(acc);
+			acc = 0;
+			n = 0;
+		}
+	}
+	if (n > 0) w.u8(acc);
+}
+function readBits(r, count) {
+	const out = new Array(count);
+	let acc = 0;
+	let have = 0;
+	for (let i = 0; i < count; i++) {
+		if (have === 0) {
+			acc = r.u8();
+			have = 8;
+		}
+		out[i] = (acc & 1) === 1;
+		acc >>= 1;
+		have--;
+	}
+	return out;
+}
+function checkByte(name, value) {
+	if (!Number.isInteger(value) || value < 0 || value > 255) throw new Error(`vterm snapshot codec: ${name} out of 0-255 range: ${String(value)}`);
+}
+function createInterner() {
+	const stringList = [""];
+	const stringMap = /* @__PURE__ */ new Map([["", 0]]);
+	const colorList = [];
+	const colorMap = /* @__PURE__ */ new Map();
+	const styleList = [];
+	const styleMap = /* @__PURE__ */ new Map();
+	function internString(s) {
+		let idx = stringMap.get(s);
+		if (idx === void 0) {
+			idx = stringList.length;
+			stringList.push(s);
+			stringMap.set(s, idx);
+		}
+		return idx;
+	}
+	/** null → 0; otherwise color-table index + 1. */
+	function colorRef(c) {
+		if (c === null) return 0;
+		checkByte("color.r", c.r);
+		checkByte("color.g", c.g);
+		checkByte("color.b", c.b);
+		if (c.index !== void 0) checkByte("color.index", c.index);
+		const key = c.index === void 0 ? `${c.r},${c.g},${c.b}` : `${c.r},${c.g},${c.b},${c.index}`;
+		let idx = colorMap.get(key);
+		if (idx === void 0) {
+			idx = colorList.length;
+			colorList.push(c.index === void 0 ? {
+				r: c.r,
+				g: c.g,
+				b: c.b
+			} : {
+				r: c.r,
+				g: c.g,
+				b: c.b,
+				index: c.index
+			});
+			colorMap.set(key, idx);
+		}
+		return idx + 1;
+	}
+	function internStyle(cell) {
+		const fgRef = colorRef(cell.fg);
+		const bgRef = colorRef(cell.bg);
+		const ulRef = colorRef(cell.underlineColor);
+		const urlRef = cell.url === null ? 0 : internString(cell.url) + 1;
+		const ulIdx = UNDERLINE_INDEX[cell.underline];
+		if (ulIdx === void 0) throw new Error(`vterm snapshot codec: unknown underline style ${String(cell.underline)}`);
+		let flags = 0;
+		if (cell.bold) flags |= F_BOLD;
+		if (cell.faint) flags |= F_FAINT;
+		if (cell.italic) flags |= F_ITALIC;
+		if (cell.overline) flags |= F_OVERLINE;
+		if (cell.strikethrough) flags |= F_STRIKE;
+		if (cell.inverse) flags |= F_INVERSE;
+		if (cell.hidden) flags |= F_HIDDEN;
+		if (cell.blink) flags |= F_BLINK;
+		if (cell.wide) flags |= F_WIDE;
+		flags |= ulIdx << UL_SHIFT;
+		const key = `${flags}|${fgRef}|${bgRef}|${ulRef}|${urlRef}`;
+		let idx = styleMap.get(key);
+		if (idx === void 0) {
+			idx = styleList.length;
+			styleList.push({
+				flags,
+				fgRef,
+				bgRef,
+				ulRef,
+				urlRef
+			});
+			styleMap.set(key, idx);
+		}
+		return idx;
+	}
+	return {
+		stringList,
+		colorList,
+		styleList,
+		internString,
+		internStyle
+	};
+}
+function buildGridColumns(grid, interner) {
+	const charAcc = createRunAccumulator();
+	const styleAcc = createRunAccumulator();
+	const lenAcc = createRunAccumulator();
+	for (const row of grid) {
+		lenAcc.push(row.length);
+		for (const cell of row) {
+			charAcc.push(interner.internString(cell.char));
+			styleAcc.push(interner.internStyle(cell));
+		}
+	}
+	return {
+		rowCount: grid.length,
+		lenRuns: lenAcc.runs,
+		charRuns: charAcc.runs,
+		styleRuns: styleAcc.runs
+	};
+}
+function writeGridSection(w, columns, softWrapped, softWrapNullable) {
+	w.varint(columns.rowCount);
+	if (softWrapNullable && softWrapped === void 0) w.u8(0);
+	else {
+		if (softWrapNullable) w.u8(1);
+		if (softWrapped === void 0) throw new Error("vterm snapshot codec: missing soft-wrap array for a required grid");
+		if (softWrapped.length !== columns.rowCount) throw new Error(`vterm snapshot codec: soft-wrap length ${softWrapped.length} != rowCount ${columns.rowCount}`);
+		writeBits(w, softWrapped);
+	}
+	writeRuns(w, columns.lenRuns);
+	writeRuns(w, columns.charRuns);
+	writeRuns(w, columns.styleRuns);
+}
+function writeStringTable(w, list) {
+	w.varint(list.length);
+	for (const s of list) {
+		const b = encoder.encode(s);
+		w.varint(b.length);
+		w.bytes(b);
+	}
+}
+function writeColorTable(w, list) {
+	w.varint(list.length);
+	for (const c of list) {
+		w.u8(c.r);
+		w.u8(c.g);
+		w.u8(c.b);
+		w.varint(c.index === void 0 ? 0 : c.index + 1);
+	}
+}
+function writeStyleTable(w, list) {
+	w.varint(list.length);
+	for (const st of list) {
+		w.varint(st.flags);
+		w.varint(st.fgRef);
+		w.varint(st.bgRef);
+		w.varint(st.ulRef);
+		w.varint(st.urlRef);
+	}
+}
+function readStringTable(r) {
+	const count = r.varint();
+	const list = new Array(count);
+	for (let i = 0; i < count; i++) {
+		const len = r.varint();
+		list[i] = decoder.decode(r.take(len));
+	}
+	return list;
+}
+function readColorTable(r) {
+	const count = r.varint();
+	const list = new Array(count);
+	for (let i = 0; i < count; i++) {
+		const cr = r.u8();
+		const cg = r.u8();
+		const cb = r.u8();
+		const idxPlus = r.varint();
+		list[i] = idxPlus === 0 ? {
+			r: cr,
+			g: cg,
+			b: cb
+		} : {
+			r: cr,
+			g: cg,
+			b: cb,
+			index: idxPlus - 1
+		};
+	}
+	return list;
+}
+function readStyleTable(r) {
+	const count = r.varint();
+	const list = new Array(count);
+	for (let i = 0; i < count; i++) list[i] = {
+		flags: r.varint(),
+		fgRef: r.varint(),
+		bgRef: r.varint(),
+		ulRef: r.varint(),
+		urlRef: r.varint()
+	};
+	return list;
+}
+function colorFromRef(ref, table) {
+	if (ref === 0) return null;
+	const c = table[ref - 1];
+	if (c === void 0) throw new Error(`vterm snapshot codec: color ref ${ref} out of range (table size ${table.length})`);
+	return c.index === void 0 ? {
+		r: c.r,
+		g: c.g,
+		b: c.b
+	} : {
+		r: c.r,
+		g: c.g,
+		b: c.b,
+		index: c.index
+	};
+}
+function makeCell(charIdx, styleIdx, strings, colors, styles) {
+	const char = strings[charIdx];
+	if (char === void 0) throw new Error(`vterm snapshot codec: char ref ${charIdx} out of range (table size ${strings.length})`);
+	const style = styles[styleIdx];
+	if (style === void 0) throw new Error(`vterm snapshot codec: style ref ${styleIdx} out of range (table size ${styles.length})`);
+	const underline = UNDERLINE_STYLES[style.flags >> UL_SHIFT & UL_MASK];
+	if (underline === void 0) throw new Error(`vterm snapshot codec: invalid underline bits in style flags ${style.flags}`);
+	let url;
+	if (style.urlRef === 0) url = null;
+	else {
+		const u = strings[style.urlRef - 1];
+		if (u === void 0) throw new Error(`vterm snapshot codec: url ref ${style.urlRef} out of range (table size ${strings.length})`);
+		url = u;
+	}
+	return {
+		char,
+		fg: colorFromRef(style.fgRef, colors),
+		bg: colorFromRef(style.bgRef, colors),
+		bold: (style.flags & F_BOLD) !== 0,
+		faint: (style.flags & F_FAINT) !== 0,
+		italic: (style.flags & F_ITALIC) !== 0,
+		underline,
+		underlineColor: colorFromRef(style.ulRef, colors),
+		overline: (style.flags & F_OVERLINE) !== 0,
+		strikethrough: (style.flags & F_STRIKE) !== 0,
+		inverse: (style.flags & F_INVERSE) !== 0,
+		hidden: (style.flags & F_HIDDEN) !== 0,
+		blink: (style.flags & F_BLINK) !== 0,
+		wide: (style.flags & F_WIDE) !== 0,
+		url
+	};
+}
+function readGridSection(r, softWrapNullable, expected, strings, colors, styles) {
+	const rowCount = r.varint();
+	let softWrapped;
+	if (softWrapNullable) {
+		const present = r.u8();
+		if (present === 0) softWrapped = void 0;
+		else if (present === 1) softWrapped = readBits(r, rowCount);
+		else throw new Error(`vterm snapshot codec: invalid soft-wrap presence byte ${present}`);
+	} else softWrapped = readBits(r, rowCount);
+	const rowLengths = expandLengths(readRuns(r));
+	if (rowLengths.length !== rowCount) throw new Error(`vterm snapshot codec: decoded ${rowLengths.length} row lengths but rowCount is ${rowCount}`);
+	if (expected) {
+		if (rowCount !== expected.rows) throw new Error(`vterm snapshot codec: grid rowCount ${rowCount} != expected ${expected.rows}`);
+		for (const len of rowLengths) if (len !== expected.cols) throw new Error(`vterm snapshot codec: grid row length ${len} != expected ${expected.cols}`);
+	}
+	let totalCells = 0;
+	for (const len of rowLengths) totalCells += len;
+	const charCursor = createRunCursor(readRuns(r));
+	const styleCursor = createRunCursor(readRuns(r));
+	if (charCursor.total !== totalCells) throw new Error(`vterm snapshot codec: char column has ${charCursor.total} cells, grid needs ${totalCells}`);
+	if (styleCursor.total !== totalCells) throw new Error(`vterm snapshot codec: style column has ${styleCursor.total} cells, grid needs ${totalCells}`);
+	const grid = new Array(rowCount);
+	for (let row = 0; row < rowCount; row++) {
+		const len = rowLengths[row];
+		const cells = new Array(len);
+		for (let col = 0; col < len; col++) cells[col] = makeCell(charCursor.next(), styleCursor.next(), strings, colors, styles);
+		grid[row] = cells;
+	}
+	return {
+		grid,
+		softWrapped
+	};
+}
+/**
+* Encode a {@link ScreenSnapshot} to a compact binary buffer. Output is
+* deterministic for identical input and decodes back to a deep-equal snapshot.
+*/
+function encodeScreenSnapshotBinary(snapshot) {
+	const w = createWriter();
+	w.u8(VERSION);
+	const header = {
+		cols: snapshot.cols,
+		rows: snapshot.rows,
+		scrollbackLimit: snapshot.scrollbackLimit,
+		activeBuffer: snapshot.activeBuffer,
+		cursor: snapshot.cursor,
+		savedState: snapshot.savedState,
+		attrs: snapshot.attrs,
+		modes: snapshot.modes,
+		margins: snapshot.margins,
+		colors: snapshot.colors,
+		tabStops: snapshot.tabStops,
+		title: snapshot.title,
+		clipboard: snapshot.clipboard,
+		cwd: snapshot.cwd,
+		notifications: snapshot.notifications,
+		viewportOffset: snapshot.viewportOffset,
+		parser: snapshot.parser,
+		unicode: snapshot.unicode
+	};
+	const headerBytes = encoder.encode(JSON.stringify(header));
+	w.varint(headerBytes.length);
+	w.bytes(headerBytes);
+	const interner = createInterner();
+	const mainColumns = buildGridColumns(snapshot.main.grid, interner);
+	const altColumns = buildGridColumns(snapshot.alt.grid, interner);
+	const scrollbackColumns = buildGridColumns(snapshot.scrollback, interner);
+	writeStringTable(w, interner.stringList);
+	writeColorTable(w, interner.colorList);
+	writeStyleTable(w, interner.styleList);
+	writeGridSection(w, mainColumns, snapshot.main.softWrapped, false);
+	writeGridSection(w, altColumns, snapshot.alt.softWrapped, false);
+	writeGridSection(w, scrollbackColumns, snapshot.scrollbackSoftWrapped, true);
+	return w.finish();
+}
+/**
+* Decode a buffer produced by {@link encodeScreenSnapshotBinary} back into a
+* {@link ScreenSnapshot}. Throws loudly on an unknown version byte, truncated
+* input, or any internal inconsistency — never returns a partial/normalized result.
+*/
+function decodeScreenSnapshotBinary(bytes) {
+	const r = createReader(bytes);
+	const version = r.u8();
+	if (version !== VERSION) throw new Error(`vterm snapshot codec: unsupported version byte ${version} (expected ${VERSION})`);
+	const headerLen = r.varint();
+	const header = JSON.parse(decoder.decode(r.take(headerLen)));
+	const strings = readStringTable(r);
+	const colors = readColorTable(r);
+	const styles = readStyleTable(r);
+	const geom = {
+		rows: header.rows,
+		cols: header.cols
+	};
+	const main = readGridSection(r, false, geom, strings, colors, styles);
+	const alt = readGridSection(r, false, geom, strings, colors, styles);
+	const scrollback = readGridSection(r, true, null, strings, colors, styles);
+	return {
+		version: 1,
+		cols: header.cols,
+		rows: header.rows,
+		scrollbackLimit: header.scrollbackLimit,
+		activeBuffer: header.activeBuffer,
+		main: {
+			grid: main.grid,
+			softWrapped: main.softWrapped
+		},
+		alt: {
+			grid: alt.grid,
+			softWrapped: alt.softWrapped
+		},
+		scrollback: scrollback.grid,
+		scrollbackSoftWrapped: scrollback.softWrapped,
+		cursor: header.cursor,
+		savedState: header.savedState,
+		attrs: header.attrs,
+		modes: header.modes,
+		margins: header.margins,
+		colors: header.colors,
+		tabStops: header.tabStops,
+		title: header.title,
+		clipboard: header.clipboard,
+		cwd: header.cwd,
+		notifications: header.notifications,
+		viewportOffset: header.viewportOffset,
+		parser: header.parser,
+		unicode: header.unicode
 	};
 }
 //#endregion
-export { createScreen as createVtermScreen };
+export { createScreen as createVtermScreen, decodeScreenSnapshotBinary, encodeScreenSnapshotBinary, serializeSnapshot };