fix(types): make TerminalSnapshot.cursorVisible required, document DECSTR limit

README.md

@@ -63,6 +63,8 @@ All dimensions are validated as positive integers. Using a terminal after `dispo
 
 `snapshot()` reports the cursor position (`cursorRow`, `cursorCol`) and its DECTCEM visibility (`cursorVisible`, toggled by `ESC[?25h` and `ESC[?25l`). With `includeCells: true`, each cell reports its text, width, optional `foreground` and `background` colors, and these SGR attributes: `bold`, `faint`, `italic`, `underline`, `inverse`, `invisible`, and `strikethrough`. An attribute is present only when it is set. `inverse` is the raw SGR 7 flag: `foreground` and `background` are not swapped, so consumers apply reverse video with their own default colors.
 
+The pinned Ghostty ignores the DECSTR soft reset (`ESC[!p`). After it, a hidden cursor stays hidden and SGR attributes stay set. Programs that reset with `ESC c` (RIS) are unaffected.
+
 ### Mouse encoding
 
 `encodeMouse` returns a `Buffer` containing the terminal input bytes for one

src/README.md

@@ -15,7 +15,7 @@ Package API (exported by `index.ts`):
 - `SnapshotOptions`: `{ includeScrollback?: boolean; includeCells?: boolean }` [src/types.ts:SnapshotOptions]
 - `VisibleLine`: `{ row: number; text: string }` [src/types.ts:VisibleLine]
 - `SnapshotCell`: `{ row; col; text; width; bold?; italic?; underline?; faint?; inverse?; invisible?; strikethrough?; foreground?; background? }` [src/types.ts:SnapshotCell]
-- `TerminalSnapshot`: `{ cols; rows; cursorRow; cursorCol; cursorVisible?; isAltScreen; visibleLines; scrollbackLines?; cells? }` [src/types.ts:TerminalSnapshot]
+- `TerminalSnapshot`: `{ cols; rows; cursorRow; cursorCol; cursorVisible; isAltScreen; visibleLines; scrollbackLines?; cells? }` [src/types.ts:TerminalSnapshot]
 - `MouseAction`: `"press" | "release" | "motion"`. `MouseButton`: `"left" | "right" | "middle" | "four"` to `"eleven"` [src/types.ts:MouseButton]
 - `MouseInputEvent`: `{ action; button?; x; y; modifiers?: MouseModifiers }`, and `MouseModifiers`: `{ shift?; ctrl?; alt? }` [src/types.ts:MouseInputEvent] [src/types.ts:MouseModifiers]
 - `MouseEncoderOptions`: `{ geometry: MouseGeometry; anyButtonPressed?; trackLastCell? }`. `MouseGeometry`: `{ screenWidth; screenHeight; cellWidth; cellHeight; paddingTop?; paddingBottom?; paddingRight?; paddingLeft? }` [src/types.ts:MouseEncoderOptions] [src/types.ts:MouseGeometry]

src/types.ts

@@ -88,11 +88,8 @@ export interface TerminalSnapshot {
   rows: number;
   cursorRow: number;
   cursorCol: number;
-  /**
-   * Cursor visibility from DECTCEM (`ESC[?25h` shows, `ESC[?25l` hides).
-   * The native binding always sets it; it is optional for compatibility.
-   */
-  cursorVisible?: boolean;
+  /** Cursor visibility from DECTCEM (`ESC[?25h` shows, `ESC[?25l` hides). */
+  cursorVisible: boolean;
   isAltScreen: boolean;
   visibleLines: VisibleLine[];
   scrollbackLines?: VisibleLine[];

test/terminal.test.ts

@@ -133,6 +133,20 @@ describeIfNative("GhosttyVtTerminal", () => {
     }
   });
 
+  // Ghostty added DECSTR in f473f31. Moving the pin past it makes this fail:
+  // then drop the README's soft-reset limit and assert the reset instead.
+  it("ignores the DECSTR soft reset with the pinned Ghostty", () => {
+    const term = createTerminal({ cols: 80, rows: 24 });
+    try {
+      term.feed("\x1b[?25l\x1b[7m\x1b[!pX");
+      const snapshot = term.snapshot({ includeCells: true });
+      expect(snapshot.cursorVisible).toBe(false);
+      expect(cellsByText(snapshot).get("X")?.inverse).toBe(true);
+    } finally {
+      term.dispose();
+    }
+  });
+
   it("updates snapshot dimensions on resize", () => {
     const term = createTerminal({ cols: 80, rows: 24 });
     try {