@tuidom/terminal-backend 0.23.2 → 0.24.0

package/dist/nodeTerminalBackend.d.ts

@@ -1,4 +1,5 @@
 import type { HostColorScheme, HostTerminalColors, ITerminalBackend } from "@tuidom/core/backend/iTerminalBackend";
+import { type CursorStyle } from "@tuidom/core/common/cursorStyle";
 import { Point, Size } from "@tuidom/core/common/geometryPromitives";
 import type { KeyPressEvent } from "@tuidom/core/input/keyEvent";
 import type { MouseToken } from "@tuidom/core/input/rawTerminalToken";
@@ -50,6 +51,10 @@ export declare class NodeTerminalBackend implements ITerminalBackend {
     private readonly frameBuffer;
     private prevGrid;
     private prevCursorPosition;
+    /** The cursor shape the terminal shows; `null` — its default, untouched until a frame asks otherwise. */
+    private prevCursorStyle;
+    /** Some frame has set a non-default cursor shape; teardown owes the terminal a `CSI 0 q`. */
+    private cursorStyleTouched;
     constructor(stdin?: NodeJS.ReadStream, stdout?: NodeJS.WriteStream, options?: {
         resizeThrottleMs?: number;
     });
@@ -115,7 +120,7 @@ export declare class NodeTerminalBackend implements ITerminalBackend {
     private clearPartialInputTimer;
     /** Emit resize only if dimensions actually changed */
     private emitResize;
-    renderFrame(grid: Grid, cursorPosition: Point | null): void;
+    renderFrame(grid: Grid, cursorPosition: Point | null, cursorStyle?: CursorStyle | null): void;
     getSize(): Size;
     setup(): void;
     teardown(): void;

package/dist/nodeTerminalBackend.js

@@ -1,4 +1,5 @@
 import { parseXColor } from "@tuidom/core/common/colorUtils";
+import { sameCursorStyle } from "@tuidom/core/common/cursorStyle";
 import { Point, Size } from "@tuidom/core/common/geometryPromitives";
 import { KeyInputParser } from "@tuidom/core/input/keyInputParser";
 import { MOUSE_TRACKING_ALL_ENABLE, MOUSE_TRACKING_DISABLE } from "@tuidom/core/input/mouseTracking";
@@ -54,6 +55,17 @@ const TITLE_POP = "\x1b[23;0t";
 function pointerShapeSequence(shape) {
     return `\x1b]22;${shape}\x1b\\`;
 }
+/**
+ * DECSCUSR (`CSI n q`) — the text cursor shape: 1/2 block, 3/4 underline, 5/6 bar (odd
+ * blinks, even is steady), 0 the terminal's default. tmux understands it and keeps it per
+ * pane, so it goes directly; terminals without it drop the sequence.
+ */
+function cursorStyleSequence(style) {
+    if (style === null)
+        return "\x1b[0 q";
+    const base = style.shape === "block" ? 1 : style.shape === "underline" ? 3 : 5;
+    return `\x1b[${(style.blinking ? base : base + 1).toString()} q`;
+}
 /**
  * Color-scheme reports (DEC private mode 2031, the Contour protocol): with the mode on the
  * terminal sends `CSI ? 997 ; 1|2 n` whenever its scheme flips; `CSI ? 996 n` asks for the
@@ -195,6 +207,10 @@ export class NodeTerminalBackend {
     frameBuffer = new StringSink();
     prevGrid = null;
     prevCursorPosition = null;
+    /** The cursor shape the terminal shows; `null` — its default, untouched until a frame asks otherwise. */
+    prevCursorStyle = null;
+    /** Some frame has set a non-default cursor shape; teardown owes the terminal a `CSI 0 q`. */
+    cursorStyleTouched = false;
     constructor(stdin = process.stdin, stdout = process.stdout, options) {
         this.stdin = stdin;
         this.stdout = stdout;
@@ -433,7 +449,7 @@ export class NodeTerminalBackend {
             cb(size);
         }
     }
-    renderFrame(grid, cursorPosition) {
+    renderFrame(grid, cursorPosition, cursorStyle = null) {
         this.prevGrid ??= new Grid(grid.size);
         const sizeChanged = this.prevGrid.width !== grid.width || this.prevGrid.height !== grid.height;
         if (sizeChanged) {
@@ -444,10 +460,13 @@ export class NodeTerminalBackend {
         this.renderer.render(grid, this.prevGrid);
         const body = this.frameBuffer.value;
         const cursorChanged = !samePoint(cursorPosition, this.prevCursorPosition);
+        // The shape of a hidden cursor doesn't matter: the terminal keeps the last one until
+        // the cursor shows again, so a frame without a cursor never writes a shape.
+        const styleChanged = cursorPosition !== null && !sameCursorStyle(cursorStyle, this.prevCursorStyle);
         // Nothing to repaint and the cursor hasn't moved → emit absolutely nothing.
         // Without this, every mouse-move event re-sent the frame wrapper (hide/show
         // cursor + reposition), making the terminal cursor flicker on plain motion.
-        if (!sizeChanged && body.length === 0 && !cursorChanged) {
+        if (!sizeChanged && body.length === 0 && !cursorChanged && !styleChanged) {
             return;
         }
         let out = "\x1b[?2026h"; // begin synchronized output
@@ -459,6 +478,12 @@ export class NodeTerminalBackend {
             out += "\x1b[?25l"; // hide cursor
         }
         out += body;
+        if (styleChanged) {
+            out += cursorStyleSequence(cursorStyle);
+            this.prevCursorStyle = cursorStyle;
+            if (cursorStyle !== null)
+                this.cursorStyleTouched = true;
+        }
         if (cursorPosition !== null) {
             out += `\x1b[${(cursorPosition.y + 1).toString()};${(cursorPosition.x + 1).toString()}H`; // position cursor
             out += "\x1b[?25h"; // show cursor
@@ -553,6 +578,13 @@ export class NodeTerminalBackend {
         }
         // Bring back the default pointer, or the shell keeps the last one (a resize arrow).
         this.setPointerShape("default");
+        // Bring back the terminal's own cursor shape — only if a frame ever changed it, so a
+        // run that never set a shape leaves the byte stream as it was.
+        if (this.cursorStyleTouched) {
+            this.writeDirect(cursorStyleSequence(null));
+            this.prevCursorStyle = null;
+            this.cursorStyleTouched = false;
+        }
         // Restore cursor
         this.stdout.write("\x1b[?25h");
         // Restore normal screen buffer

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tuidom/terminal-backend",
-    "version": "0.23.2",
+    "version": "0.24.0",
     "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.23.2"
+        "@tuidom/core": "0.24.0"
     }
 }