✨ add clear option to alternateBuffer

Add `{ clear?: boolean }` option to `ALTSCREEN()` and
`alternateBuffer()`. When `clear` is false, uses xterm private mode 47
to switch without clearing the alternate buffer contents.

Closes #13

Author: cowboyd

settings.ts

@@ -19,9 +19,11 @@ export function settings(...sequence: Setting[]): Setting {
   };
 }
 
-export function alternateBuffer(): Setting {
+export function alternateBuffer(
+  options?: { clear?: boolean },
+): Setting {
   return {
-    apply: ALTSCREEN(),
+    apply: ALTSCREEN(options),
     revert: MAINSCREEN(),
   };
 }

termcodes.ts

@@ -55,19 +55,27 @@ export function HIDECURSOR(): Uint8Array {
 }
 
 /**
- * Switch to the alternate screen buffer (xterm private mode 1049).
+ * Switch to the alternate screen buffer.
  *
- * Saves the cursor and switches to a clean alternate screen. Use
- * {@link MAINSCREEN} to switch back.
+ * Saves the cursor and switches to the alternate screen. When `clear` is
+ * `true` (the default), the alternate buffer is cleared on entry. When
+ * `false`, the existing contents are preserved.
+ *
+ * Use {@link MAINSCREEN} to switch back.
  *
  * @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html | xterm control sequences}
  */
-export function ALTSCREEN(): Uint8Array {
-  return CSI("?1049h");
+export function ALTSCREEN(options?: { clear?: boolean }): Uint8Array {
+  let { clear = true } = options ?? {};
+  if (clear) {
+    return CSI("?1049h");
+  } else {
+    return CSI("?47h");
+  }
 }
 
 /**
- * Switch back to the main screen buffer (xterm private mode 1049).
+ * Switch back to the main screen buffer.
  *
  * Restores the cursor and returns to the main screen with scrollback intact.
  *

test/settings.test.ts

@@ -18,6 +18,12 @@ describe("settings", () => {
       expect(str(s.apply)).toBe("\x1b[?1049h");
       expect(str(s.revert)).toBe("\x1b[?1049l");
     });
+
+    it("uses mode 47 when clear is false", () => {
+      let s = alternateBuffer({ clear: false });
+      expect(str(s.apply)).toBe("\x1b[?47h");
+      expect(str(s.revert)).toBe("\x1b[?1049l");
+    });
   });
 
   describe("cursor", () => {