vterm.js 0.7.0 → 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
@@ -35,6 +35,8 @@ Part of the [vterm](https://github.com/beorn/vterm) monorepo.
 
 ## Install
 
+> Install from npm; a git install resolves the TypeScript source and runs only under Bun.
+
 ```bash
 npm install vterm.js
 ```
@@ -138,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;
   /**
@@ -204,6 +211,10 @@ interface Snapshot {
     originMode: boolean;
     autoWrap: boolean;
     charsetG0: boolean;
+    /** True when DEC Special Graphics is designated as G1. Absent in older snapshots: ASCII. */
+    charsetG1?: boolean;
+    /** True when SO has invoked G1 into GL. Absent in older snapshots: SI/G0. */
+    activeG1?: boolean;
   };
   attrs: ScreenAttrsSnapshot;
   modes: {
@@ -242,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[];
@@ -268,6 +281,10 @@ interface Snapshot {
   };
   unicode: {
     charsetG0: boolean;
+    /** True when DEC Special Graphics is designated as G1. Absent in older snapshots: ASCII. */
+    charsetG1?: boolean;
+    /** True when SO has invoked G1 into GL. Absent in older snapshots: SI/G0. */
+    activeG1?: boolean;
     lastChar: string;
     pendingRegionalIndicator: string | null;
     afterZWJ: boolean;
@@ -564,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;