@visulima/ansi 3.0.3 → 3.0.4

package/dist/cursor.d.ts

@@ -1,56 +1,437 @@
 /**
-Gracefully restore the CLI cursor on exit.
-
-Prevent the cursor you have hidden interactively from remaining hidden if the process crashes.
-
-It does nothing if run in a non-TTY context.
-
-@example
-```
-import restoreCursor from 'restore-cursor';
-
-restoreCursor();
-```
-*/
-declare function restoreCursor(): void;
-
-declare const SAVE_CURSOR_DEC: string;
-declare const RESTORE_CURSOR_DEC: string;
-declare const CURSOR_UP_1: string;
-declare const CURSOR_DOWN_1: string;
-declare const CURSOR_FORWARD_1: string;
-declare const CURSOR_BACKWARD_1: string;
-declare const REQUEST_CURSOR_POSITION: string;
-declare const REQUEST_EXTENDED_CURSOR_POSITION: string;
-declare const cursorBackward: (count?: number) => string;
-declare const cursorDown: (count?: number) => string;
-declare const cursorForward: (count?: number) => string;
-declare const cursorHide: string;
-declare const cursorToColumn1: string;
-declare const cursorLeft: (count?: number) => string;
-declare const cursorHorizontalAbsolute: (column?: number) => string;
-declare const cursorMove: (x: number, y: number) => string;
-declare const cursorNextLine: (count?: number) => string;
-declare const cursorPreviousLine: (count?: number) => string;
-declare const cursorRestore: string;
-declare const cursorSave: string;
-declare const cursorShow: string;
-declare const cursorTo: (x: number, y?: number) => string;
-declare const cursorPosition: (row: number, column?: number) => string;
-declare const cursorHorizontalForwardTab: (count?: number) => string;
-declare const cursorBackwardTab: (count?: number) => string;
-declare const eraseCharacter: (count?: number) => string;
-declare const cursorVerticalAbsolute: (row?: number) => string;
-declare const cursorUp: (count?: number) => string;
-declare enum CursorStyle {
+ * Saves the cursor position, character attributes (like color, intensity), and character set (G0-G3).
+ * This is the DECSC (Save Cursor) sequence: `ESC 7`.
+ * Used in conjunction with {@link RESTORE_CURSOR_DEC} (`ESC 8`) to restore the saved state.
+ * @remarks This is a DEC private sequence, widely supported.
+ * For SCO-compatible terminals (like Linux console before full ANSI/VT support, or some older Unix systems),
+ * `ESC s` ({@link cursorSave}) might be used for a similar purpose, though DECSC/DECRC are more comprehensive.
+ * @see {@link RESTORE_CURSOR_DEC}
+ * @see {@link cursorSave} (provides a version that adapts to Terminal.app)
+ */
+export declare const SAVE_CURSOR_DEC: string;
+/**
+ * Restores the previously saved cursor position, character attributes, and character set.
+ * This is the DECRC (Restore Cursor) sequence: `ESC 8`.
+ * Used after {@link SAVE_CURSOR_DEC} (`ESC 7`) has saved the state.
+ * @remarks This is a DEC private sequence, widely supported.
+ * For SCO-compatible terminals, `ESC u` ({@link cursorRestore}) might be used.
+ * @see {@link SAVE_CURSOR_DEC}
+ * @see {@link cursorRestore} (provides a version that adapts to Terminal.app)
+ */
+export declare const RESTORE_CURSOR_DEC: string;
+/**
+ * Moves the cursor up one line in the same column. If the cursor is at the top line, behavior is undefined (may ignore or scroll).
+ * This is the CUU (Cursor Up) sequence: `CSI A` (equivalent to `CSI 1A`).
+ * @see {@link cursorUp} for moving multiple lines or with a count.
+ * @see {@link CURSOR_DOWN_1}
+ * @see {@link CURSOR_FORWARD_1}
+ * @see {@link CURSOR_BACKWARD_1}
+ */
+export declare const CURSOR_UP_1: string;
+/**
+ * Moves the cursor down one line in the same column. If the cursor is at the bottom line, behavior is undefined (may ignore or scroll).
+ * This is the CUD (Cursor Down) sequence: `CSI B` (equivalent to `CSI 1B`).
+ * @see {@link cursorDown} for moving multiple lines or with a count.
+ * @see {@link CURSOR_UP_1}
+ * @see {@link CURSOR_FORWARD_1}
+ * @see {@link CURSOR_BACKWARD_1}
+ */
+export declare const CURSOR_DOWN_1: string;
+/**
+ * Moves the cursor forward (right) one column in the same line. If the cursor is at the rightmost column, behavior is terminal-dependent (may wrap if DECAWM is set, or ignore).
+ * This is the CUF (Cursor Forward) sequence: `CSI C` (equivalent to `CSI 1C`).
+ * @see {@link cursorForward} for moving multiple columns or with a count.
+ * @see {@link CURSOR_UP_1}
+ * @see {@link CURSOR_DOWN_1}
+ * @see {@link CURSOR_BACKWARD_1}
+ */
+export declare const CURSOR_FORWARD_1: string;
+/**
+ * Moves the cursor backward (left) one column in the same line. If the cursor is at the leftmost column, behavior is undefined (may ignore).
+ * This is the CUB (Cursor Backward) sequence: `CSI D` (equivalent to `CSI 1D`).
+ * @see {@link cursorBackward} for moving multiple columns or with a count.
+ * @see {@link CURSOR_UP_1}
+ * @see {@link CURSOR_DOWN_1}
+ * @see {@link CURSOR_FORWARD_1}
+ */
+export declare const CURSOR_BACKWARD_1: string;
+/**
+ * Asks the terminal to report its current cursor position using the DSR (Device Status Report) sequence.
+ * The sequence sent is `CSI 6n`.
+ * The terminal is expected to respond with a CPR (Cursor Position Report) sequence in the format `CSI <row>;<col>R`,
+ * where `<row>` and `<col>` are 1-indexed coordinates.
+ * @remarks
+ * This is an active report, meaning the application sends a request and waits for a response from the terminal
+ * via standard input.
+ * Parsing the response requires reading from `stdin` and interpreting the escape sequence.
+ * @see {@link REQUEST_EXTENDED_CURSOR_POSITION} for a version that might include page number.
+ * @see {@link https://vt100.net/docs/vt510-rm/DSR-CPR.html} DSR/CPR documentation.
+ * @returns The ANSI escape sequence `CSI 6n`.
+ */
+export declare const REQUEST_CURSOR_POSITION: string;
+/**
+ * Asks the terminal to report its extended cursor position, potentially including the page number.
+ * The sequence sent is `CSI ?6n` (a DEC private DSR variant).
+ * The response format from the terminal is typically `CSI ? <row>;<col>;<page>R` (1-indexed).
+ * If the terminal does not support this extended version, it might fall back to the standard DSR response
+ * or not respond in a recognizable way.
+ * @remarks
+ * Support for this DEC private DSR is less universal than the standard `CSI 6n`.
+ * It's generally used in contexts where page numbers (e.g., in a multi-page document or buffer)
+ * are relevant.
+ * @see {@link REQUEST_CURSOR_POSITION} for the standard cursor position report.
+ * @returns The ANSI escape sequence `CSI ?6n`.
+ */
+export declare const REQUEST_EXTENDED_CURSOR_POSITION: string;
+/**
+ * Moves the cursor backward (left) a specific number of columns from its current position.
+ * This uses the CUB (Cursor Backward) sequence: `CSI <count>D`.
+ * @param count The number of columns to move backward. Must be a positive integer. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence for moving the cursor backward.
+ * @example
+ * ```typescript
+ * cursorBackward(5); // Moves cursor 5 columns to the left.
+ * cursorBackward();  // Moves cursor 1 column to the left.
+ * ```
+ * @see {@link CURSOR_BACKWARD_1}
+ * @see {@link cursorForward}
+ * @see {@link cursorLeft} (alias for this function)
+ */
+export declare const cursorBackward: (count?: number) => string;
+/**
+ * Moves the cursor down a specific number of rows from its current position, staying in the same column.
+ * This uses the CUD (Cursor Down) sequence: `CSI <count>B`.
+ * @param count The number of rows to move down. Must be a positive integer. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence for moving the cursor down.
+ * @example
+ * ```typescript
+ * cursorDown(3); // Moves cursor 3 rows down.
+ * cursorDown();  // Moves cursor 1 row down.
+ * ```
+ * @see {@link CURSOR_DOWN_1}
+ * @see {@link cursorUp}
+ */
+export declare const cursorDown: (count?: number) => string;
+/**
+ * Moves the cursor forward (right) a specific number of columns from its current position.
+ * This uses the CUF (Cursor Forward) sequence: `CSI <count>C`.
+ * @param count The number of columns to move forward. Must be a positive integer. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence for moving the cursor forward.
+ * @example
+ * ```typescript
+ * cursorForward(4); // Moves cursor 4 columns to the right.
+ * cursorForward();  // Moves cursor 1 column to the right.
+ * ```
+ * @see {@link CURSOR_FORWARD_1}
+ * @see {@link cursorBackward}
+ */
+export declare const cursorForward: (count?: number) => string;
+/**
+ * Hides the cursor. This uses the DECTCEM (Text Cursor Enable Mode) sequence `CSI ?25l` to set the mode to "invisible".
+ * @remarks
+ * This is a DEC private mode. Visibility can be restored using {@link cursorShow} (`CSI ?25h`).
+ * The appearance of the cursor (when visible) can often be controlled by {@link setCursorStyle}.
+ * @see {@link cursorShow}
+ * @see {@link TextCursorEnableMode} in `mode.ts` (represents DEC Mode 25).
+ * @returns The ANSI escape sequence `CSI ?25l`.
+ */
+export declare const cursorHide: string;
+/**
+ * Moves the cursor to column 1 (the beginning) of the current line.
+ * This uses the CHA (Cursor Horizontal Absolute) sequence `CSI G` (equivalent to `CSI 1G`).
+ * @remarks
+ * This is different from a carriage return (`\r` or `CR`), which also moves to the beginning
+ * of the line but can have other side effects (like overprinting) in some contexts.
+ * `CSI G` specifically sets the horizontal position.
+ * @see {@link cursorHorizontalAbsolute} for moving to any absolute column.
+ * @returns The ANSI escape sequence `CSI G`.
+ */
+export declare const cursorToColumn1: string;
+/**
+ * Moves the cursor left by `count` columns. This is an alias for {@link cursorBackward}.
+ * Sequence: `CSI <count>D`.
+ * @param count The number of columns to move left. Defaults to `1`.
+ * @returns The ANSI escape sequence.
+ * @see {@link cursorBackward}
+ */
+export declare const cursorLeft: (count?: number) => string;
+/**
+ * Moves the cursor to the specified absolute horizontal column `column` (1-indexed) on the current line.
+ * This uses the CHA (Cursor Horizontal Absolute) sequence: `CSI <column>G`.
+ * @param column The 1-indexed column number to move to. E.g., `1` for the first column.
+ * If `column` is less than 1, behavior is terminal-dependent (often treated as 1).
+ * Defaults to `1` if not provided.
+ * @returns The ANSI escape sequence.
+ * @example
+ * ```typescript
+ * cursorHorizontalAbsolute(10); // Moves to column 10 of the current line.
+ * cursorHorizontalAbsolute();   // Moves to column 1 of the current line.
+ * ```
+ * @see {@link cursorToColumn1} (moves to column 1 specifically).
+ * @see {@link cursorTo} for moving to an (x,y) coordinate, which can also use CHA for x-only movement.
+ */
+export declare const cursorHorizontalAbsolute: (column?: number) => string;
+/**
+ * Moves the cursor relative to its current position by `x` columns and `y` rows.
+ *
+ * This function combines CUU (Up), CUD (Down), CUF (Forward), and CUB (Backward) sequences
+ * as needed based on the signs and magnitudes of `x` and `y`.
+ *
+ * - Positive `x` moves right (CUF: `CSI <x>C`).
+ * - Negative `x` moves left (CUB: `CSI <-x>D`).
+ * - Positive `y` moves down (CUD: `CSI <y>B`).
+ * - Negative `y` moves up (CUU: `CSI <-y>A`).
+ *
+ * If both `x` and `y` are 0, an empty string is returned as no movement is needed.
+ * @param x The number of columns to move. Positive values move right, negative values move left.
+ * @param y The number of rows to move. Positive values move down, negative values move up.
+ * @returns A string containing the necessary ANSI escape sequence(s) to perform the relative move,
+ * or an empty string if no movement (`x=0`, `y=0`).
+ * @example
+ * ```typescript
+ * console.log(cursorMove(5, -2));  // Moves 5 columns right and 2 rows up.
+ *                                // Output: CSI 5C CSI 2A (or similar)
+ * console.log(cursorMove(-3, 0)); // Moves 3 columns left.
+ *                                // Output: CSI 3D
+ * console.log(cursorMove(0, 4));  // Moves 4 rows down.
+ *                                // Output: CSI 4B
+ * ```
+ */
+export declare const cursorMove: (x: number, y: number) => string;
+/**
+ * Moves the cursor to the beginning (column 1) of the next line, `count` times.
+ * This uses the CNL (Cursor Next Line) sequence: `CSI <count>E`.
+ * @param count The number of lines to move down. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence.
+ * @example
+ * ```typescript
+ * cursorNextLine(2); // Moves to the beginning of the line 2 lines down.
+ * cursorNextLine();  // Moves to the beginning of the next line.
+ * ```
+ */
+export declare const cursorNextLine: (count?: number) => string;
+/**
+ * Moves the cursor to the beginning (column 1) of the previous line, `count` times.
+ * This uses the CPL (Cursor Previous Line) sequence: `CSI <count>F`.
+ * @param count The number of lines to move up. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence.
+ * @example
+ * ```typescript
+ * cursorPreviousLine(3); // Moves to the beginning of the line 3 lines up.
+ * cursorPreviousLine();  // Moves to the beginning of the previous line.
+ * ```
+ */
+export declare const cursorPreviousLine: (count?: number) => string;
+/**
+ * Restores the last saved cursor position, character attributes (like color and style),
+ * and character set state (G0-G3 mapping).
+ *
+ * This function adapts to the environment:
+ * - For Apple's Terminal.app (and environments where `isTerminalApp` is true),
+ * it uses DECRC (`ESC 8`, see {@link RESTORE_CURSOR_DEC}).
+ * - For other terminals (typically SCO-compatible or more standard ANSI environments),
+ * it uses SCOSRC (`ESC u`).
+ * @remarks
+ * `DECSC`/`DECRC` (`ESC 7`/`ESC 8`) are generally more comprehensive and widely supported for full state saving/restoring
+ * in VT100+ compatible terminals.
+ * `SCOSC`/`SCOSRC` (`ESC s`/`ESC u`) are from the SCO console world and might save/restore fewer attributes.
+ * @returns The ANSI escape sequence for restoring the cursor state, adapted to the terminal environment.
+ * @see {@link cursorSave} for the corresponding save operation.
+ * @see {@link SAVE_CURSOR_DEC}
+ * @see {@link RESTORE_CURSOR_DEC}
+ * @see {@link isTerminalApp}
+ */
+export declare const cursorRestore: string;
+/**
+ * Saves the current cursor position, character attributes, and character set state.
+ *
+ * This function adapts to the environment:
+ * - For Apple's Terminal.app (and environments where `isTerminalApp` is true),
+ * it uses DECSC (`ESC 7`, see {@link SAVE_CURSOR_DEC}).
+ * - For other terminals, it uses SCOSC (`ESC s`).
+ * @returns The ANSI escape sequence for saving the cursor state, adapted to the terminal environment.
+ * @see {@link cursorRestore} for the corresponding restore operation.
+ * @see {@link SAVE_CURSOR_DEC}
+ * @see {@link RESTORE_CURSOR_DEC}
+ * @see {@link isTerminalApp}
+ */
+export declare const cursorSave: string;
+/**
+ * Shows the cursor. This uses the DECTCEM (Text Cursor Enable Mode) sequence `CSI ?25h` to set the mode to "visible".
+ * @remarks
+ * This is a DEC private mode. Visibility can be hidden using {@link cursorHide} (`CSI ?25l`).
+ * The appearance of the cursor (when visible) can often be controlled by {@link setCursorStyle}.
+ * @see {@link cursorHide}
+ * @see {@link TextCursorEnableMode} in `mode.ts` (represents DEC Mode 25).
+ * @returns The ANSI escape sequence `CSI ?25h`.
+ */
+export declare const cursorShow: string;
+/**
+ * Moves the cursor to a specific coordinate (0-indexed) on the screen.
+ * The top-left corner of the screen is `(x: 0, y: 0)`.
+ *
+ * - If both `x` (column) and `y` (row) are provided, it uses the CUP (Cursor Position)
+ * sequence: `CSI <y+1>;<x+1>H`. Note that CUP is 1-indexed.
+ * - If only `x` (column) is provided (or `y` is `undefined`), it moves the cursor horizontally
+ * to the absolute column `x` on the current line. This uses the CHA (Cursor Horizontal Absolute)
+ * sequence: `CSI <x+1>G`. Note that CHA is 1-indexed.
+ * @param x The 0-indexed column number. `0` is the leftmost column.
+ * @param y (Optional) The 0-indexed row number. `0` is the topmost row.
+ * If undefined, only horizontal movement to column `x` occurs.
+ * @returns The ANSI escape sequence for moving the cursor.
+ * @example
+ * ```typescript
+ * cursorTo(0, 0);       // Moves to top-left (row 0, col 0) -> CSI 1;1H
+ * cursorTo(10, 5);      // Moves to row 5, col 10 -> CSI 6;11H
+ * cursorTo(7);          // Moves to column 7 of the current line -> CSI 8G
+ * ```
+ * @see {@link cursorPosition} for a 1-indexed version of CUP.
+ * @see {@link cursorHorizontalAbsolute} for 1-indexed horizontal positioning.
+ */
+export declare const cursorTo: (x: number, y?: number) => string;
+/**
+ * Moves the cursor to a specific position (1-indexed) on the screen using the CUP (Cursor Position) sequence.
+ * The top-left corner of the screen is `(row: 1, column: 1)`.
+ *
+ * - If `column` is provided: `CSI <row>;<column>H`.
+ * - If `column` is undefined: `CSI <row>H` (moves to column 1 of the specified `row`).
+ * @param row The 1-indexed row number. `1` is the topmost row.
+ * @param column (Optional) The 1-indexed column number. `1` is the leftmost column.
+ * If undefined, the cursor moves to column 1 of the specified `row`.
+ * @returns The ANSI escape sequence.
+ * @example
+ * ```typescript
+ * cursorPosition(1, 1);    // Moves to top-left (row 1, col 1) -> CSI 1;1H
+ * cursorPosition(5, 10);   // Moves to row 5, col 10 -> CSI 5;10H
+ * cursorPosition(3);       // Moves to row 3, col 1 -> CSI 3H
+ * ```
+ * @see {@link cursorTo} for a 0-indexed version.
+ */
+export declare const cursorPosition: (row: number, column?: number) => string;
+/**
+ * Moves the cursor forward (right) to the next tab stop, `count` times.
+ * This uses the CHT (Cursor Horizontal Forward Tabulation) sequence: `CSI <count>I`.
+ * Tab stops are typically every 8 columns by default, but can be configured by terminal settings or HTS/TBC sequences.
+ * @param count The number of tab stops to advance. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence.
+ * @example
+ * ```typescript
+ * cursorHorizontalForwardTab(2); // Advances two tab stops.
+ * cursorHorizontalForwardTab();  // Advances one tab stop.
+ * ```
+ * @see {@link cursorBackwardTab}
+ */
+export declare const cursorHorizontalForwardTab: (count?: number) => string;
+/**
+ * Moves the cursor backward (left) to the previous tab stop, `count` times.
+ * This uses the CBT (Cursor Backward Tabulation) sequence: `CSI <count>Z`.
+ * Tab stops are typically every 8 columns by default.
+ * @param count The number of tab stops to move backward. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence.
+ * @example
+ * ```typescript
+ * cursorBackwardTab(2); // Moves back two tab stops.
+ * cursorBackwardTab();  // Moves back one tab stop.
+ * ```
+ * @see {@link cursorHorizontalForwardTab}
+ */
+export declare const cursorBackwardTab: (count?: number) => string;
+/**
+ * Erases `count` characters from the current cursor position forward (inclusive of the character at the cursor position).
+ * Characters are replaced with spaces. The cursor position does not change.
+ * This uses the ECH (Erase Character) sequence: `CSI <count>X`.
+ * @param count The number of characters to erase. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence.
+ * @example
+ * ```typescript
+ * // Assuming text "Hello World" and cursor at 'H':
+ * process.stdout.write(eraseCharacter(5)); // Erases "Hello", leaves "     World"
+ * ```
+ */
+export declare const eraseCharacter: (count?: number) => string;
+/**
+ * Moves the cursor to the absolute vertical line (row) `row` (1-indexed), maintaining the current column.
+ * This uses the VPA (Vertical Line Position Absolute) sequence: `CSI <row>d`.
+ * @param row The 1-indexed row number to move to. Defaults to `1` (the first row).
+ * If `row` is less than 1, behavior is terminal-dependent (often treated as 1).
+ * @returns The ANSI escape sequence.
+ * @example
+ * ```typescript
+ * cursorVerticalAbsolute(10); // Moves to row 10, same column.
+ * cursorVerticalAbsolute();   // Moves to row 1, same column.
+ * ```
+ */
+export declare const cursorVerticalAbsolute: (row?: number) => string;
+/**
+ * Moves the cursor up a specific number of rows from its current position, staying in the same column.
+ * This uses the CUU (Cursor Up) sequence: `CSI <count>A`.
+ * @param count The number of rows to move up. Must be a positive integer. Defaults to `1`.
+ * If `count` is 0 or negative, it might be treated as 1 by some terminals or ignored.
+ * @returns The ANSI escape sequence for moving the cursor up.
+ * @example
+ * ```typescript
+ * cursorUp(2); // Moves cursor 2 rows up.
+ * cursorUp();  // Moves cursor 1 row up.
+ * ```
+ * @see {@link CURSOR_UP_1}
+ * @see {@link cursorDown}
+ */
+export declare const cursorUp: (count?: number) => string;
+/**
+ * Represents the available cursor styles that can be set using the DECSCUSR (Set Cursor Style) sequence.
+ * The sequence is typically `CSI <Ps> SP q` (note the space before `q`).
+ * @remarks
+ * - `0` or `1` (Blinking Block) are often treated as the default by many terminals if DECSCUSR is not supported or reset.
+ * - Actual appearance can vary between terminal emulators.
+ * - Some terminals might not support all styles or DECSCUSR itself.
+ */
+export declare enum CursorStyle {
+    /** Blinking Bar (often an I-beam shape) cursor. (Corresponds to `Ps=5`) */
     BlinkingBar = 5,
-    BlinkingBlock = 1,
+    /** Blinking Block cursor. (Corresponds to `Ps=0` or `Ps=1` in `CSI Ps SP q`) */
+    BlinkingBlock = 1,// Or 0, often interchangeable for default blinking block
+    /** Blinking Underline cursor. (Corresponds to `Ps=3`) */
     BlinkingUnderline = 3,
+    /**
+     * Default cursor style (Ps=0). The appearance is terminal-dependent, typically a blinking block.
+     * Using `0` explicitly can sometimes reset to the terminal's configured default if it differs from `1`.
+     */
     Default = 0,
+    /** Steady (non-blinking) Bar (I-beam) cursor. (Corresponds to `Ps=6`) */
     SteadyBar = 6,
+    /** Steady (non-blinking) Block cursor. (Corresponds to `Ps=2`) */
     SteadyBlock = 2,
+    /** Steady (non-blinking) Underline cursor. (Corresponds to `Ps=4`) */
     SteadyUnderline = 4
 }
-declare const setCursorStyle: (style: CursorStyle | number) => string;
-
-export { CURSOR_BACKWARD_1, CURSOR_DOWN_1, CURSOR_FORWARD_1, CURSOR_UP_1, CursorStyle, REQUEST_CURSOR_POSITION, REQUEST_EXTENDED_CURSOR_POSITION, RESTORE_CURSOR_DEC, SAVE_CURSOR_DEC, cursorBackward, cursorBackwardTab, cursorDown, cursorForward, cursorHide, cursorHorizontalAbsolute, cursorHorizontalForwardTab, cursorLeft, cursorMove, cursorNextLine, cursorPosition, cursorPreviousLine, cursorRestore, cursorSave, cursorShow, cursorTo, cursorToColumn1, cursorUp, cursorVerticalAbsolute, eraseCharacter, restoreCursor, setCursorStyle };
+/**
+ * Sets the terminal cursor style using the DECSCUSR (Set Cursor Style) sequence.
+ * The generated sequence is `CSI <styleValue> SP q` (note the space before `q`).
+ * @param style The desired cursor style. This can be a value from the {@link CursorStyle} enum
+ * or a raw number corresponding to the `Ps` parameter of DECSCUSR.
+ * @returns The ANSI escape sequence to set the cursor style.
+ * @example
+ * ```typescript
+ * import { setCursorStyle, CursorStyle } from '@visulima/ansi/cursor';
+ *
+ * process.stdout.write(setCursorStyle(CursorStyle.BlinkingUnderline)); // Sets blinking underline: CSI 3 q
+ * process.stdout.write(setCursorStyle(CursorStyle.SteadyBar));       // Sets steady bar: CSI 6 q
+ * process.stdout.write(setCursorStyle(0));                           // Sets default (usually blinking block): CSI 0 q
+ * ```
+ * @remarks
+ * - Support for DECSCUSR and specific styles can vary between terminal emulators.
+ * - `0` and `1` often both result in a blinking block, with `0` sometimes being a more explicit "reset to default."
+ * @see {@link CursorStyle} for predefined style values.
+ * @see {@link https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Set-cursor-style-DECSCUSR} XTerm DECSCUSR documentation.
+ * @see {@link https://vt100.net/docs/vt510-rm/DECSCUSR.html} VT510 DECSCUSR documentation.
+ */
+export declare const setCursorStyle: (style: CursorStyle | number) => string;
+export { default as restoreCursor } from "restore-cursor";