@tuidom/terminal-backend 0.10.0 → 0.11.1

package/dist/nodeTerminalBackend.d.ts

@@ -3,6 +3,8 @@ import { Point, Size } from "@tuidom/core/common/geometryPromitives";
 import type { KeyPressEvent } from "@tuidom/core/input/keyEvent";
 import type { MouseToken } from "@tuidom/core/input/rawTerminalToken";
 import { Grid } from "@tuidom/core/rendering/grid";
+/** OSC 0 — icon name and window title at once; BEL is the terminator everyone understands. */
+export declare function windowTitleSequence(title: string): string;
 /**
  * Real terminal backend: reads from process.stdin, writes to process.stdout.
  * Handles alternate screen, raw mode, cursor visibility, signal cleanup.
@@ -29,6 +31,8 @@ export declare class NodeTerminalBackend implements ITerminalBackend {
     private lastEmittedSize;
     private resizePending;
     private cleanupHandlers;
+    /** The title stack got a push from {@link setWindowTitle}; teardown owes it a pop. */
+    private titlePushed;
     private readonly isTmux;
     private readonly isGnuScreen;
     private readonly inputParser;
@@ -67,6 +71,14 @@ export declare class NodeTerminalBackend implements ITerminalBackend {
      * TMUX passthrough is applied automatically when running inside TMUX.
      */
     writeOscSequence(sequence: string): void;
+    /**
+     * Set the terminal window title (OSC 0). Written directly, never through tmux
+     * passthrough: tmux understands OSC 0/2 itself and keeps it as the pane title
+     * (`#{pane_title}`, `#T`), from where `set-titles` / `automatic-rename-format` carry it
+     * to the outer window and the tmux window name. The first call saves the current title
+     * on the terminal's title stack; {@link teardown} restores it.
+     */
+    setWindowTitle(title: string): void;
     onInput(callback: (event: KeyPressEvent) => void): void;
     onMouse(callback: (event: MouseToken) => void): void;
     onPaste(callback: (text: string) => void): void;

package/dist/nodeTerminalBackend.js

@@ -38,6 +38,19 @@ const MODIFY_OTHER_KEYS_DISABLE = "\x1b[>4;0m";
  */
 const BRACKETED_PASTE_ENABLE = "\x1b[?2004h";
 const BRACKETED_PASTE_DISABLE = "\x1b[?2004l";
+/**
+ * Window-title stack (XTWINOPS): `CSI 22 ; 0 t` saves the icon and window titles,
+ * `CSI 23 ; 0 t` restores them — the same push/pop vim does around its own title, so the
+ * shell's title comes back on exit. tmux keeps the stack per pane; terminals without it
+ * ignore the sequence.
+ */
+const TITLE_PUSH = "\x1b[22;0t";
+const TITLE_POP = "\x1b[23;0t";
+/** OSC 0 — icon name and window title at once; BEL is the terminator everyone understands. */
+export function windowTitleSequence(title) {
+    // A control character inside the title would cut the sequence short.
+    return `\x1b]0;${title.replace(/[\x00-\x1f\x7f]/g, " ")}\x07`;
+}
 /**
  * Keyboard-protocol probe: query current Kitty flags (`CSI ? u`) immediately followed by
  * Primary Device Attributes (`CSI c`). Only Kitty-capable terminals answer the first; every
@@ -138,6 +151,8 @@ export class NodeTerminalBackend {
     lastEmittedSize = null;
     resizePending = false;
     cleanupHandlers = [];
+    /** The title stack got a push from {@link setWindowTitle}; teardown owes it a pop. */
+    titlePushed = false;
     isTmux;
     isGnuScreen;
     inputParser = new KeyInputParser();
@@ -187,6 +202,20 @@ export class NodeTerminalBackend {
     writeOscSequence(sequence) {
         this.writePassthrough(sequence);
     }
+    /**
+     * Set the terminal window title (OSC 0). Written directly, never through tmux
+     * passthrough: tmux understands OSC 0/2 itself and keeps it as the pane title
+     * (`#{pane_title}`, `#T`), from where `set-titles` / `automatic-rename-format` carry it
+     * to the outer window and the tmux window name. The first call saves the current title
+     * on the terminal's title stack; {@link teardown} restores it.
+     */
+    setWindowTitle(title) {
+        if (!this.titlePushed) {
+            this.writeDirect(TITLE_PUSH);
+            this.titlePushed = true;
+        }
+        this.writeDirect(windowTitleSequence(title));
+    }
     onInput(callback) {
         this.inputCallbacks.push(callback);
     }
@@ -460,6 +489,11 @@ export class NodeTerminalBackend {
         this.stdout.write("\x1b[?25h");
         // Restore normal screen buffer
         this.stdout.write("\x1b[?1049l");
+        // Restore the title saved by the first setWindowTitle — direct, like the title itself
+        if (this.titlePushed) {
+            this.writeDirect(TITLE_POP);
+            this.titlePushed = false;
+        }
         // Remove stdin listener
         if (this.onDataHandler) {
             this.stdin.removeListener("data", this.onDataHandler);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tuidom/terminal-backend",
-    "version": "0.10.0",
+    "version": "0.11.1",
     "type": "module",
     "description": "Experimental terminal UI DOM — real terminal backend for Node (tty, ANSI diffing, Kitty protocol). API is unstable.",
     "license": "MIT",
@@ -28,6 +28,6 @@
         "./*": "./dist/*.js"
     },
     "dependencies": {
-        "@tuidom/core": "0.10.0"
+        "@tuidom/core": "0.11.1"
     }
 }