vterm.js 0.7.1 → 0.8.0

package/README.md

@@ -20,7 +20,7 @@ Part of the [vterm](https://github.com/beorn/vterm) monorepo.
 - **Synchronized output** — mode 2026
 - **Application cursor keys & keypad**
 - **Kitty keyboard protocol** — progressive-enhancement flags with a push/pop/set stack (`CSI u`)
-- **OSC sequences** — window title (OSC 0/2), hyperlinks (OSC 8), clipboard (OSC 52), colors
+- **OSC sequences** — independent icon/window labels (OSC 0 sets both, OSC 1 icon, OSC 2 window), hyperlinks (OSC 8), clipboard (OSC 52), colors
 - **DCS sequences** — consumed and ignored, XTVERSION response
 - **Device attributes** — DA1/DA2/DA3 responses
 - **Device status reports** — DSR responses
@@ -140,6 +140,8 @@ console.log(restored.getText()) // "Hello, Bold Green World!" — text and style
 
 **Soft-wrap history.** `Snapshot` carries `scrollbackSoftWrapped: boolean[]` alongside `scrollback` — bit `i` true means scrollback row `i` wraps into row `i+1` (one logical line split across rows); an absent array (older stored v1 snapshots) is treated as all-false. Phase-1 history re-links a wrapped row by emitting it at full width with no line break, so the receiver's own autowrap re-records the bit as the row scrolls back.
 
+**Icon/window labels.** `Snapshot.title` remains the window title. New v1 snapshots include optional `iconLabel`, including empty strings; the binary codec preserves whether that field is present. Only `restore()` defaults legacy absence to `title` to preserve old CSI20 behavior; historical OSC0 versus OSC2 intent cannot be recovered. An own `undefined`, `null` or other non-string value is rejected. Older readers ignore the new JSON-header key and lose independent icon semantics. `getTitle()` and `title$` remain window-only. `includeTitle:true` emits a nonempty window title with OSC2, preserving the receiver's independent icon instead of the former OSC0 side effect. Default title omission and empty-title omission remain; ANSI replay does not transfer the icon label.
+
 ### Ops and taps
 
 `apply(op)` is the single public write entry — the same seam a session journal records and replays. An op is coarse, serializable data; **bytes stay the canonical encoding** (an `output` op is just bytes, deterministically re-parsed on replay — vterm never reifies a per-VT-action op):

package/dist/index.d.mts

@@ -85,6 +85,13 @@ interface ScreenOptions {
   cols?: number;
   rows?: number;
   scrollbackLimit?: number;
+  /**
+   * The embedder renders or relays kitty graphics images, so this screen may
+   * claim them: graphics queries answer OK and the kittyGraphics mode is true.
+   * Default false — this screen stores no image, so it refuses queries and
+   * reports no capability (#31020).
+   */
+  kittyGraphicsImages?: boolean;
   /** Callback for DA1/DA2/DSR responses — write these back to the PTY */
   onResponse?: (data: string) => void;
   /**
@@ -246,6 +253,8 @@ interface Snapshot {
   };
   tabStops: number[];
   title: string;
+  /** Independent icon label. Legacy absence restores from title; a supplied value must be a string. */
+  iconLabel?: string;
   clipboard: string;
   cwd: string;
   notifications: string[];
@@ -572,7 +581,7 @@ declare function createScreen(options?: ScreenOptions): Screen;
 interface SerializeOptions {
   /** Emit scrollback history rows before the screen paint. Default: true. */
   includeScrollback?: boolean;
-  /** Emit the window title (OSC 0) when non-empty. Default: false. */
+  /** Emit only the window title (OSC 2) when non-empty, preserving the receiver's icon label. Default: false. */
   includeTitle?: boolean;
   /** Emit OSC 8 hyperlinks for cell and pending-pen urls. Default: true. */
   hyperlinks?: boolean;

package/dist/index.mjs

@@ -478,6 +478,7 @@ function createScreen(options = {}) {
 	let rows = options.rows ?? 24;
 	let scrollbackLimit = options.scrollbackLimit ?? 1e3;
 	const onResponse = options.onResponse;
+	const kittyGraphicsImages = options.kittyGraphicsImages ?? false;
 	const maxStringSequenceLength = options.maxStringSequenceLength ?? 16777216;
 	if (!Number.isSafeInteger(maxStringSequenceLength) || maxStringSequenceLength < 0) throw new RangeError("maxStringSequenceLength must be a non-negative safe integer");
 	let mainGrid = makeGrid(cols, rows);
@@ -503,6 +504,7 @@ function createScreen(options = {}) {
 	let savedCurY = 0;
 	let attrs = resetAttrs();
 	let title = "";
+	let iconLabel = "";
 	let useAltScreen = false;
 	let bracketedPaste = false;
 	let applicationCursor = false;
@@ -519,7 +521,6 @@ function createScreen(options = {}) {
 	let syncOutput = false;
 	let kittyKeyboardFlags = 0;
 	let kittyKeyboardStack = [];
-	let hasKittyGraphics = false;
 	let scrollTop = 0;
 	let scrollBottom = rows - 1;
 	let leftRightMarginMode = false;
@@ -716,6 +717,7 @@ function createScreen(options = {}) {
 		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);
+		if (Object.hasOwn(value, "iconLabel")) assertString("iconLabel", value.iconLabel);
 		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");
@@ -782,9 +784,6 @@ 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";
@@ -1465,20 +1464,18 @@ function createScreen(options = {}) {
 			case "t": {
 				const op = parts[0] ?? 0;
 				if (!onResponse) break;
-				const CELL_H = 16;
-				const CELL_W = 8;
 				switch (op) {
 					case 14:
-						onResponse(`\x1b[4;${rows * CELL_H};${cols * CELL_W}t`);
+						onResponse("\x1B[4;0;0t");
 						break;
 					case 16:
-						onResponse(`\x1b[6;${CELL_H};${CELL_W}t`);
+						onResponse("\x1B[6;0;0t");
 						break;
 					case 18:
 						onResponse(`\x1b[8;${rows};${cols}t`);
 						break;
 					case 20:
-						onResponse(`\x1b]L${title}\x1b\\`);
+						onResponse(`\x1b]L${iconLabel}\x1b\\`);
 						break;
 					case 21: onResponse(`\x1b]l${title}\x1b\\`);
 				}
@@ -2302,6 +2299,9 @@ function createScreen(options = {}) {
 		const value = semicolonIdx === -1 ? "" : oscString.substring(semicolonIdx + 1);
 		switch (code) {
 			case 0:
+				iconLabel = value;
+				title = value;
+				break;
 			case 2:
 				title = value;
 				break;
@@ -2328,7 +2328,9 @@ function createScreen(options = {}) {
 					});
 				}
 				break;
-			case 1: break;
+			case 1:
+				iconLabel = value;
+				break;
 			case 7:
 				cwd = value;
 				break;
@@ -2660,7 +2662,7 @@ function createScreen(options = {}) {
 				break;
 			}
 			case 776:
-				if (onResponse) onResponse(`\x1b]776;${CELL_W_PX};${CELL_H_PX};${FONT_ASCENT_PX}\x1b\\`);
+				if (onResponse) onResponse("\x1B]776;0;0;0\x1B\\");
 				break;
 			case 7770:
 				if (value === "?") {
@@ -2698,7 +2700,7 @@ function createScreen(options = {}) {
 					advancedClipboard = "";
 				}
 				break;
-			case 1337: if (value === "ReportCellSize" && onResponse) onResponse("\x1B]1337;ReportCellSize=16;8\x1B\\");
+			case 1337: if (value === "ReportCellSize" && onResponse) onResponse("\x1B]1337;ReportCellSize=0;0\x1B\\");
 			else if (value === "RequestCapabilities" && onResponse) onResponse("\x1B]1337;Capabilities=\x1B\\");
 		}
 	}
@@ -2728,7 +2730,6 @@ function createScreen(options = {}) {
 	}
 	function handleAPC(data) {
 		if (!data.startsWith("G")) return;
-		hasKittyGraphics = true;
 		const semicolonIdx = data.indexOf(";");
 		const kvPart = semicolonIdx >= 0 ? data.substring(1, semicolonIdx) : data.substring(1);
 		const params = {};
@@ -2736,7 +2737,11 @@ function createScreen(options = {}) {
 			const eqIdx = pair.indexOf("=");
 			if (eqIdx >= 0) params[pair.substring(0, eqIdx)] = pair.substring(eqIdx + 1);
 		}
-		if (params.a === "q" && onResponse) onResponse(`\x1b_Gi=${params.i ?? "0"};OK\x1b\\`);
+		if (params.a === "q" && onResponse) {
+			if (kittyGraphicsImages) {
+				if (params.q !== "1" && params.q !== "2") onResponse(`\x1b_Gi=${params.i ?? "0"};OK\x1b\\`);
+			} else if (params.q !== "2") onResponse(`\x1b_Gi=${params.i ?? "0"};ENOTSUP\x1b\\`);
+		}
 	}
 	function softReset() {
 		insertMode = false;
@@ -2791,6 +2796,7 @@ function createScreen(options = {}) {
 		};
 		attrs = resetAttrs();
 		title = "";
+		iconLabel = "";
 		useAltScreen = false;
 		bracketedPaste = false;
 		applicationCursor = false;
@@ -2807,7 +2813,6 @@ function createScreen(options = {}) {
 		syncOutput = false;
 		kittyKeyboardFlags = 0;
 		kittyKeyboardStack = [];
-		hasKittyGraphics = false;
 		hasSixel = false;
 		sixelImages = [];
 		scrollTop = 0;
@@ -3531,7 +3536,7 @@ function createScreen(options = {}) {
 				syncOutput,
 				kittyKeyboardFlags,
 				kittyKeyboardStack: [...kittyKeyboardStack],
-				kittyGraphics: hasKittyGraphics,
+				kittyGraphics: kittyGraphicsImages,
 				colorSchemeReporting,
 				decColumn: decColumnMode,
 				altScroll: altScrollMode,
@@ -3550,6 +3555,7 @@ function createScreen(options = {}) {
 			},
 			tabStops: [...tabStops].sort((a, b) => a - b),
 			title,
+			iconLabel,
 			clipboard,
 			cwd,
 			notifications: [...notifications],
@@ -3635,7 +3641,6 @@ function createScreen(options = {}) {
 		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;
@@ -3650,6 +3655,7 @@ function createScreen(options = {}) {
 		colorStack.push(...snapshotValue.colors.stack.map(cloneColorStateSnapshot));
 		tabStops = new Set(snapshotValue.tabStops);
 		title = snapshotValue.title;
+		iconLabel = Object.hasOwn(snapshotValue, "iconLabel") ? snapshotValue.iconLabel : snapshotValue.title;
 		clipboard = snapshotValue.clipboard;
 		cwd = snapshotValue.cwd;
 		notifications = [...snapshotValue.notifications];
@@ -3798,7 +3804,7 @@ function createScreen(options = {}) {
 			case "leftRightMargin": return leftRightMarginMode;
 			case "colorSchemeReporting": return colorSchemeReporting;
 			case "kittyKeyboard": return kittyKeyboardFlags > 0;
-			case "kittyGraphics": return hasKittyGraphics;
+			case "kittyGraphics": return kittyGraphicsImages;
 			case "sixel": return hasSixel;
 			default: return false;
 		}
@@ -3876,7 +3882,7 @@ function createScreen(options = {}) {
 			leftRightMargin: leftRightMarginMode,
 			colorSchemeReporting,
 			kittyKeyboard: kittyKeyboardFlags > 0,
-			kittyGraphics: hasKittyGraphics,
+			kittyGraphics: kittyGraphicsImages,
 			sixel: hasSixel
 		};
 	}
@@ -4321,7 +4327,7 @@ function serializeSnapshot(snapshot, options = {}) {
 		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\\`);
+	if (options.includeTitle === true && snapshot.title.length > 0) out.push(`\x1b]2;${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++) {
@@ -4819,6 +4825,7 @@ function readGridSection(r, softWrapNullable, expected, strings, colors, styles)
 * deterministic for identical input and decodes back to a deep-equal snapshot.
 */
 function encodeScreenSnapshotBinary(snapshot) {
+	if (Object.hasOwn(snapshot, "iconLabel") && typeof snapshot.iconLabel !== "string") throw new TypeError("vterm snapshot codec: invalid iconLabel");
 	const w = createWriter();
 	w.u8(VERSION);
 	const header = {
@@ -4835,6 +4842,7 @@ function encodeScreenSnapshotBinary(snapshot) {
 		colors: snapshot.colors,
 		tabStops: snapshot.tabStops,
 		title: snapshot.title,
+		...Object.hasOwn(snapshot, "iconLabel") ? { iconLabel: snapshot.iconLabel } : {},
 		clipboard: snapshot.clipboard,
 		cwd: snapshot.cwd,
 		notifications: snapshot.notifications,
@@ -4868,6 +4876,7 @@ function decodeScreenSnapshotBinary(bytes) {
 	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)));
+	if (Object.hasOwn(header, "iconLabel") && typeof header.iconLabel !== "string") throw new TypeError("vterm snapshot codec: invalid iconLabel");
 	const strings = readStringTable(r);
 	const colors = readColorTable(r);
 	const styles = readStyleTable(r);
@@ -4903,6 +4912,7 @@ function decodeScreenSnapshotBinary(bytes) {
 		colors: header.colors,
 		tabStops: header.tabStops,
 		title: header.title,
+		...Object.hasOwn(header, "iconLabel") ? { iconLabel: header.iconLabel } : {},
 		clipboard: header.clipboard,
 		cwd: header.cwd,
 		notifications: header.notifications,

package/package.json

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